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
- available resources and actions
Figshare API uses OAuth 1.0 protocol to handle the user authentication process.
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.
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.
Example request Authorization headerAuthorization: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”
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.
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
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.
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.
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
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.
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).
- 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
- 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)
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.
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 ?
Enter search terms or a module, class or function name.