API feature list
The figshare api v2 is accessible at https://api.figshare.com/v2. All
communication is done through https and all data is encoded as JSON
.
- Sending parameters
- Resource representations
- Authentication
- Errors
- Searching, filtering and pagination
- Rate limiting
- Conditional requests
- CORS policy
- Endpoints
- collections
- items
- projects
Sending parameters
More often than not you need to send parameters to an endpoint. For
GET
requests these are usualy sent in the query string but for POST
and PUT
requests they are usually in the body of the request.
Query string
Query strings can contain parameters encoded as application/x-www-form-urlencoded
. Very common for GET
requests.
Example: Sending page
parameter when listing articles:
GET /v2/articles?page=3 HTTP/1.1
Host: api.figshare.com
Authorization: token a287ab8c7ebdbe6
Request json body
POST
and PUT
request usualy read their params from the body of the
http request. Our API only understands application/json
encoded
bodies.
Example: Sending search_for
parameter when searching for articles:
POST /v2/articles/search HTTP/1.1
Host: api.figshare.com
Authorization: token a287ab8c7ebdbe6
{
"search_for": "figshare"
}
Resource representations
Resources can be presented differently across endpoints. Usually endpoints that return a list of resources will send a lighter representation of each resource while an endpoint for an individual resource will use a more detailed and complete representation.
Representations for each resource type are documented here and the documentation for each endpoint will specify what kind of representation it's using.
Blank resource fields are included in the representation as null
instead
of being omitted.
Authentication
The v2 API supports OAuth2 access tokens, issued as described in the oauth documentation page.
In addition to oauth access tokens, you can also use a personal token which grants you full access to your account. Personal tokens can be created and managed from the applications page at figshare.
Any of these tokens can be used to authenticate and there are 2 options to include them in requests:
HTTP header (recommended)
GET /v2/token HTTP/1.1
Host: api.figshare.com
Authorization: token ACCESS_TOKEN
Example with curl
:
curl -H "Authorization: token ACCESS_TOKEN" https://api.figshare.com/v2
Query param:
GET /v2/token?access_token=ACCESS_TOKEN HTTP/1.1
Host: api.figshare.com
Example with curl
:
curl https://api.figshare.com/v2?access_token=ACCESS_TOKEN
Errors
Endpoints can respond with error responses. The common error responses for all endpoints are presented below and errors specific to individual enpoints are documented along with the endpoint.
Each error response will have a specific HTTP status code and a JSON body with the following fields:
Field | Description |
---|---|
message | A human friendly message explaining the error. |
code | A machine friendly error code, used by the dev team to identify the error. |
data | An object containing extra information about the error. Documented for each error. |
404 Not found
Trying to access resources that do not exist, will trigger this response from the API.
This is also returned if you try to access a resource on which you don't
have a read
permission.
400 Bad request
Sending a body that cannot be parsed as JSON will result in this error response.
422 Unprocessable Entity
Sending an invalid data structure in the body will trigger this error. Invalid data can be any of the following:
- missing field
- invalid value for a field
- any other rules specific to an endpoint
401 Unauthorized
This error is returned when the authorization was unsuccessfull. This can be either due to:
- missing authorization info in the request
- invalid or unknown authorization info
- expired or disabled account
403 Forbidden
This response is presented whenever you try to do something which is not permitted for your current authorization. authorization info
Searching, filtering and pagination
Endpoints that list items usually support any of the following features:
- pagination
- ordering
- searching
- filtering
Pagination params
Pagination can be done by specifing either page
and page_size
params
pair or the limit
and offset
params pair. If confusing combinations
appear in a request, a 422 Unprocessable Entity
will be returned.
field | type | default | description |
---|---|---|---|
page |
int | 1 | Page number |
page_size |
int | 10 | The number of results included on a page |
limit |
int | 10 | Number of results included on a page |
offset |
int | 0 | Where to start the listing(the offset of the first result) |
Please note that there's a limit on the maximum offset or page number you can require.
The offset is currently limited at 1000 and if exceeded a 422 Unprocessable Entity
error will be returned. For pages, it depends on the page_size
but for a page_size
of 10
, the maximum page would be 1000 / 10 = 100
Ordering params
Ordering is done via the order
and order_direction
params.
field | type | default | description |
---|---|---|---|
order |
string | varies | The field by which to order. Default varies by endpoint/resource. For articles and collections, valid values are: published_date , modified_date , views , shares , downloads and cites . |
order_direction |
string | varies | Only asc and desc values are supported. Default varies by endpoint/resource |
Searching params
field | type | description |
---|---|---|
search_for |
string | Search endpoints require this field. Usually min length is 3 |
Filtering params
Some endpoints allow filtering results. Filters are extra fields in the body and the documentation for each endpoint will present them in detail.
Rate limiting
Not implemented at this point.
Conditional requests
Most responses should return an ETag header and a Last-Modified header. You can use the values of these headers to create conditional requests. We encourage to use these whenever possible.
CORS policy
The API supports CORS for AJAX requests from any origin.