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=...
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
.
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.
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.
Appropriate HTTP status codes are always returned and should be evaluated.
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 referenceauthor
Author of concerning entityproject
projects
shared
A project that has been shared with other authors of EasyBibsubscribed
A project which the user is subscibed tocitation
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
Resources and methods are restricted by scopes. Implied are access_token
and Accept
header.
Make an authenticated request to
GET https://data.easybib.com/user/?access_token={token}
{
"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"
}
]
}
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
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:
citation.json
and paste the content from the example into it.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:
201
designates the citation was created successfullyLocation
header points to created citation