Integrate the API - Api @ EasyBib

Every request must include an access_token to authorize itself. Read about how to get this token at the chapter before.

GET https://data.easybib.com/user/?access_token=...

API versioning

The EasyBib Api versions itself by requsting the client to send a header. Possible values for the Accept header are:

Accept: application/vnd.com.easybib.data+json
Accept: application/vnd.com.easybib.autocite+json

The corrosponding vocabulary is returned in the response as well:

Content-Type: application/vnd.com.easybib.data+json
Content-Type: application/vnd.com.easybib.autocite+json

By default application/vnd.com.easybib.data+json is assumed. Unknown values yield a 400 Bad Request.

Future updates to EasyBib's API

Drastic changes in the API will be introduced with a new Content-Type and Accept header.

When the client sends application/vnd.com.easybib.data+json they will receive the original response per spec, whereas application/vnd.com.easybib.data.v1+json would yield a different or extended response.

Hypermedia

EasyBib's APIs utilize hypermedia. This means the API is completely RESTful. The the client needs to understand the vocabulary of the API. The vocabulary is designated by the client's Accept header.

Because EasyBib's API's are hypermedia, it's discouraged to hardcode endpoints into your client code. The API is fully discoverable, as an example start off by issueing a request for the current user from http://data.easybib.com/user.

Response

Appropriate HTTP status codes are always returned and should be evaluated.

Vocabulary

status Required string

Attribute with possible values of ok or error.
msg Required if status error string

With status: error, a msg attribute is mandatory and will give more details about the error.
data Required object or array

The requested data. Requesting a list (https://data.easybib.com/projects/): The type of data will be an array. All array elements will be of type object that has data and links attribute. Requesting only one resource (https://data.easybib.com/project/abc): The type of data will be an object. Each object has an attribute data and links (exception is https://data.easybib.com/user/).
links Required array

List of hypermedia relations to discover additional resources. Each hypermedia relation contains rel, href and title attributes.
rel Required string

Each hypermedia relation contains a rel attribute with the identifier of the relation.
- me: Self reference
- author Author of concerning entity
- project
- projects
- shared A project that has been shared with other authors of EasyBib
- subscribed A project which the user is subscibed to
- citation
- citations
- comment
- comments
href Required string

The URL for the resource stated in rel
type Required string

The Accept header that is required to set for requesting this resource

Example Request/Response

Resources and methods are restricted by scopes. Implied are access_token and Accept header.

Request https://data.easybib.com/user/

Make an authenticated request to

GET https://data.easybib.com/user/?access_token={token}

Response https://data.easybib.com/user/

{
    "status":"ok",
    "data":{
        "first": "Example",
        "last": "User",
        "email": "example@example.com",
        "role": "mybib"
    }
    "links":[
        {
            "href":"https://data.easybib.com/user/",
            "rel":"me",
            "type":"application/vnd.com.easybib.data+json",
            "title":"Test User"
        },
        {
            "href":"https://data.easybib.com/projects/",
            "rel":"projects",
            "type":"application/vnd.com.easybib.data+json",
            "title":"Projects"
        },
        {
            "href":"https://data.easybib.com/projects/?filter=shared",
            "rel":"shared",
            "type":"application/vnd.com.easybib.data+json",
            "title":"Shared"
        },
        {
            "href":"https://data.easybib.com/projects/?filter=subscribed",
            "rel":"subscribed",
            "type":"application/vnd.com.easybib.data+json",
            "title":"Subscribed"
        }
    ]
}

Possible actions from this response

To update the user, send
```
PUT https://data.easybib.com/user/
```
Get list of projects by using
```
GET https://data.easybib.com/projects/
```

Get list of shared projects by using

GET https://data.easybib.com/projects/?filter=shared

Get list of subscribed projects by using

GET https://data.easybib.com/projects/?filter=subscribed

Add a citation to a project

To create a new citation in a project, issue a POST request to the collection.

The payload of the request contains a data object with all the relevant data.

POST https://data.easybib.com/projects/projectID/citations/
{
    "data": {
        "source": "book",
        "pubtype": {
            "main": "pubnonperiodical"
        },
        "contributors": [
            {
                "last": "Salinger",
                "first": "J. D.",
                "function": "author"
            }
        ],
        "pubnonperiodical": {
            "title": "The Catcher in the Rye",
            "publisher": "Little, Brown and Company",
            "year": "1951"
        }
    }
}

An example with libcurl's command line utility:

Create a file called citation.json and paste the content from the example into it.
Replace 'projectID' with the ID of a project you own.

Issue the following command:

$ curl https://data.easybib.com/projects/projectID/citations/ \
--request POST \
--header "Authorization: Bearer YOUR-ACCESS-TOKEN" \
--header "Accept: application/vnd.com.easybib.data+json" \
-d @citation.json

Server response (formatted):

HTTP/1.1 201 Created
Content-Type: application/json
Transfer-Encoding: chunked
Connection: close
Location: https://data.easybib.com/projects/projectID/citations/citationID
Cache-Control: no-cache
Date: Tue, 16 Jul 2013 12:49:00 GMT
{
    "links": [
        {
            "href":"https://data.easybib.com/projects/projectID/citations/citationID",
            "rel":"me",
            "type":"application/vnd.com.easybib.data+json",
            "title":"The Catcher in the Rye"
        }
    ],
    "data": {
        "source": "book",
        "pubtype": {
            "main":"pubnonperiodical"
        },
        "contributors": [
            {
                "last": "Salinger",
                "first": "J. D.",
                "function": "author"
            }
        ],
        "pubnonperiodical": {
            "title": "The Catcher in the Rye",
            "publisher": "Little, Brown and Company",
            "year": "1951"
        }
    }
}

Important notes:

HTTP status code 201 designates the citation was created successfully
HTTP Location header points to created citation

Integrate the API Learn how to integrate our APIs.