Api

epnoi API provides programmatic access to functionality and content of the system. Version 1 of the API provides an initial set of functionalities to add sources, group documents in domains and extract useful information such as: topics, terms, relations and entities from them.

The API is both a WS-REST following the Hypermedia As The Engine Of Application State (HATEOAS) principle and a Graph Query interface. Currently, the return format used for all the endpoints is JSON.

From the web-service point of view, it is an API that follows the Representational State Transfer (REST) style. As you know, it is a stateless service so you need to include credentials for every secure request to the service. To avoid this continuous exchange of sensitive information, we have adopted the protocol flow proposed by OAuth considering the epnoi service as Authorization and Resource Server.

Some details about resources and operations are presented below. However, if you are impatient ( like me ) , you can follow this 4-steps-guide to start exploring a group of documents.

Endpoints

You directly can see our list of common searches with examples using this API.

Users

First of all, you have to sign-up in the system creating a User with your personal information (username and password).

After that, you will receive as response a valid token associated to your credentials. As from now, you can operate only including that token in the Authorization HTTP header for each request.

• GET users/: retrieve user collections
• GET users/{id}: retrieve user instance
• PUT users/{id}: update user information
• POST users/: create user instance
• DELETE users/{id}: remove user instance

Sources

A Source may be a folder, a compressed file, a OAI-PMH server or a RSS server

• GET sources: retrieve source collections
• GET sources/{id}: retrieve source instance
• PUT sources/{id}: update source instance
• POST sources/: create source instance
• DELETE sources: remove source collections
• DELETE sources/{id}: remove source instance

Domains

A Domain is a group of Documents

• GET domains: retrieve domain collections
• GET domains/{id}: retrieve domain instance
• PUT domains/{id}: update domain instance
• POST domains/: create domain instance
• DELETE domains: remove domain collections
• DELETE domains/{id}: remove domain instance

Documents

A Document is a resource with text, images and so on.

• GET documents: retrieve document collections
• GET documents/{id}: retrieve document instance
• PUT documents/{id}: update document instance
• POST documents: create document instance
• DELETE documents: remove document collections
• DELETE documents/{id}: remove document instance

Items

An Item is a text or an image of a Document.

• GET items: retrieve item collections
• GET items/{id}: retrieve item instance
• PUT items/{id}: update item instance
• POST items: create item instance
• DELETE items: remove item collections
• DELETE items/{id}: remove item instance

Topics

A Topic is a set of words related in a domain

• GET topics: retrieve topic collections
• GET topics/{id}: retrieve topic instance
• PUT topics/{id}: update topic instance
• POST topics: create topic instance
• DELETE topics: remove topic collections
• DELETE topics/{id}: remove topic instance

Parts

A Part is an abstract division of a Item

• GET parts: retrieve part collections
• GET parts/{id}: retrieve part instance
• PUT parts/{id}: update part instance
• POST parts: create part instance
• DELETE parts: remove part collections
• DELETE parts/{id}: remove part instance

Words

A Word is the smallest unit of a Part. It can be a Term or an Entity.

• GET words: retrieve word collections
• GET words/{id}: retrieve word instance
• PUT words/{id}: update word instance
• POST words: create word instance
• DELETE words: remove word collections
• DELETE words/{id}: remove word instance

Relations

A relation is a connection between Entities or Terms. So, it can be a Semantic Relation between Terms or an Associative Relation between Entities

• GET relations: retrieve relation collections
• GET relations/{id}: retrieve relation instance
• PUT relations/{id}: update relation instance
• POST relations: create relation instance
• DELETE relations: remove relation collections
• DELETE relations/{id}: remove relation instance