Figshare API intro

This documentation is intended for programmers who are writing client applications that interact with Figshare.

This document is meant to give users an overview of the API and its components

• authentication
• available resources and actions
• searching

Authentication

Figshare API uses OAuth 1.0 protocol to handle the user authentication process.

There are two distinct scenarios:

• create an application that is going to access only your account
• create an application that is going to access other’s users accounts

In both casses you have to create a new application on the Applications section on figshare.com . Once the application is created you will be given 2 sets of key/secret pairs, the consumer key/secret pair and the access token key/secret pair.

If your application is going to access only your account, then you can start using the consumer and access token pairs and make oauth signed requests from your application. Check out the Demo Client for sample code.

If your application is intended for other users and will require access to the users accounts, then you will have to go through the 3-legged oauth process described bellow.

3-legged OAuth flow

1. First step: Get a Request Token

In this step the application will issue a GET request to get a request_token.

The API endpoint URL used in this step is http://api.figshare.com/v1/pbl/oauth/request_token.

The HTTP method used is GET.

Required oauth parameters will be sent in the HTTP Headers.

sample_header

Example request Authorization header

Authorization:

oauth_version=”1.0”,

oauth_nonce=”42955739”,

oauth_timestamp=”1338880125”,

oauth_consumer_key=”test_key”,

oauth_signature_method=”HMAC-SHA1”,

oauth_signature=”cmUMOmkK2jP5tWtWzXDxnb5iY8I%3D”,

oauth_callback=”http://applicationsite.com/callback”

Fields details

Required field	Description
oauth_version	The required OAuth version is 1.0
oauth_nonce	Random, user-generated string. Unique for every request.
oauth_timestamp	The timestamp is expressed in the number of seconds since January1, 1970 00:00:00 GMT. This value must be at max +-300 seconds of the current time.
oauth_consumer_key	Unique key generated when the application was created
oauth_signature_method	Required method is HMAC-SHA1
oauth_signature	Signature string generated by the HMAC-SHA1 method
oauth_callback	figshare API will redirect the user to this URL after the user authorize access to his account. If empty, the callback URL used will be the one specified when the application was created. If not empty, it will overwrite the one used when the application was created.

Sample Request

GET /v1/pbl/oauth/request_token HTTP/1.1
Host: api.figshare.com
Authorization: OAuth realm="",oauth_nonce="45326939",oauth_timestamp="1345795426",oauth_consumer_key="K0kmYikjYhsSLElhdxzQgQ",oauth_signature_method="HMAC-SHA1",oauth_version="1.0",oauth_signature="XHZ/Imo6dqhxKEnICIwlXD34Tik%3D"
Accept-Encoding: identity, deflate, compress, gzip
Accept: */*
User-Agent: python-requests/0.13.3 CPython/2.6.6 Linux/2.6.32-5-amd64

Sample Response

HTTP/1.1 200 OK
Content-Length: 426
Content-Type: text/html; charset=UTF-8
'oauth_token=4Hi8BcwJg8qYmT3qQ7tGCw4a3jZxWEbL4NPQTiSEQPUFsHKwOU9aeYMTM0NjA3MzMyMC42Mw&oauth_token_secret=MzR2BZzfmLaTkjADpZLG5MWCf7BlG18FMBMcGxvJ2b42JtFLIGAxMzQ2MDczMzIwLjYzbTZkOWQ5dGE&oauth_expires_in=3600&oauth_request_auth_url=https%253A%2F%2Fapi.figshare.com%2Fv1%2Fpbl%2Foauth%2Fauthorize%253Foauth_token%253D4Hi8BcwJg8qYmT3qQ7tGCw4a3jZxWEbL4NPQTiSEQPUFsHKwOU9aeYMTM0NjA3MzMyMC42Mw&oauth_callback_confirmed=True'

2. Second step: Get User Authorization

Once the request token is received the application will redirect the user to login and authorize the application. The API endpoint URL used in this step is http://api.figshare.com/v1/pbl/oauth/authorize.

Sample Request

GET /v1/pbl/oauth/authorize?oauth_token=TQwpbzy5QLt6QS2PGSVdJgullxECIq2N2CMwHCioexegpcc1x57yfUMTM0NTc5NzE2MC45MQ HTTP/1.1
Host: api.figshare.com
Connection: keep-alive

The user will have to login in order to authorize the application. One the user has granted access he will be redirect to the callback URL specified when the application was created, or to the URL specified in the parameter oauth_callback.

Two parameters are appended to the callback URL:

Callback URL parameters	Description
oauth_token	The request token received in the first step (Get a Request Token)
oauth_verifier	The oauth verifier is a verification code tied to the request token. The oauth verifier and request token must be both provided in the last step, when exchanging them for an access token.

If no callback URL is provided (usually desktop applications don’t have a callback URL) the user will receive a oauth_verifier (PIN code) that will be displayed in the browser. The user can then copy this PIN code and return to the application and introduce it there so that the application can continue the oauth flow.

3. Third step: Get an Access Token

In this final step the application will exchange the Request Token with an Access Token. The oauth verifier is included in the Authorization headers. The API endpoint URL used in this step is http://api.figshare.com/v1/pbl/oauth/access_token.

Sample Request

POST /v1/pbl/oauth/access_token HTTP/1.1
Host: api.figshare.com
Authorization: OAuth realm="",oauth_nonce="78169889",oauth_timestamp="1345794742",oauth_signature_method="HMAC-SHA1",oauth_consumer_key="K0kmYikjYhsSLElhdxzQgQ",oauth_verifier="BEU2VABMCY",oauth_version="1.0",oauth_token="TQwpbzy5QLt6QS2PGSVdJgullxECIq2N2CMwHCioexegpcc1x57yfUMTM0NTc5NzE2MC45MQ",oauth_signature="HnhlFz2Mysbd9jSYJCjgQUI9kRg%3D"
Accept-Encoding: identity, deflate, compress, gzip
Accept: */*
User-Agent: python-requests/0.13.3 CPython/2.6.6 Linux/2.6.32-5-amd64

Sample Response

HTTP/1.1 200 OK
Content-Length: 162
Content-Type: application/json; charset=UTF-8

'oauth_token=RUtiLT20M8f1Y0OKCqwAOwYQ9XkRuLKhplGg1ibuU7kARUtiLT20M8f1Y0OKCqwAOw&oauth_token_secret=JgGXAhdrD8AxxbJxlRlYqA&xoauth_figshare_id=13483'

Once in posession of both access token and consumer key/secret pairs you can access protected resources from the user account. Check out Demo Client for more information.

Available resources and actions

Figshare tries to make available as much information as possible while keeping a strong emphasis on the private space. The API offers the posibility to query the figshare database even to the public (no authentication required).

At this point public users can:

• list public articles from the figshare database
• make queries based on keyword, date intervals, authors, tags, title, categories againts the figshare database
• view full public article details based on the article id

Authenticated users can:

• get full listing/details of their articles
• query for authors and also create new authors
• view their stats
• fully manage their articles (add/remove files, tags, authors, categories)

Searching

The API tries to offer an advanced search engine for the users. Figshare makes have use of indexing to offer a fast and up-to-date database of articles. You can search by keyword and filter based on title, authors, tags, date, categories.

Note

Figshare is working to also index the uploaded files (metadata and content). Soon the search engine will also offer the posibility to search inside the uploaded files

For more information on how to search the figshare database check out How do I search for an article ? What filters are available ?