API Overview: Difference between revisions

From Safe Creative API
Jump to navigation Jump to search
w>Jguillo
No edit summary
No edit summary
 
(28 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= API architecture =
= API architecture =
[[File:Arquitecture.png|frame|API architecture]]
Safe Creative API is a REST-like interface to Safe Creative services. It is stateless and is divided in 3 main areas
* '''Core''': Main services accessible through <tt><nowiki>http://api.safecreative.org</nowiki></tt>
* '''Upload''': API for uploading works, accessible through several dedicated upload servers (see [[work.upload.lookup]])
* '''Search''': Public services for searching works


Safe Creative API is a REST-like interface to Safe Creative services. It is stateless and is divided in 4 main areas
There are three trust levels for applications using Safe Creative API
* Core: Main services accessible through <nowiki>http://api.safecreative.org</nowiki>
* '''Public API''': Anyone can use these services without any previous requirement. These services allow access to public registration information, as if visiting the web site.
* Upload: API for uploading works, accessible through several upload servers
* '''Standard API''': This comprises the bulk of Safe Creative services. You need an application key to access these components. Usually a user's authorization key is also needed.
* Search: Services for searching works accessible through <nowiki>http://search.safecreative.org</nowiki>
* '''Partners API''': Some components are reserved for use by [http://en.safecreative.net/partners/ Safe Creative partners]. Contact [mailto:community@safecreative.org community@safecreative.org] if you want to become a partner.
* Semantic: Semantic services accessible through <nowiki>http://search.safecreative.org</nowiki>
 
[[File:Arquitecture.png|center|API architecture]]
 
There are two levels of trust when using Safe Creative API
 
* Public API: Anyone can use these services
* Partners API: Some components are reserved for use by [http://en.safecreative.net/partners/ Safe Creative partners]. Contact administration@safecreative.org if you want to become a partner.
 
[[File:APITrust.png|center|API trust levels]]


See also:
* [[About works]]
* [[Common URLs]]


= Obtaining the keys to use the API =
= Obtaining the keys to use the API =
Line 28: Line 26:
* Web site: Public URL of the site of the application
* Web site: Public URL of the site of the application
* API callback URL: Private URL used by Safe Creative to notify different types of events. See [[API callbacks]]
* API callback URL: Private URL used by Safe Creative to notify different types of events. See [[API callbacks]]
* API bringback URL: URL provided to the client user as the final step of key authorization. i.e., user will be redirect to this url after authorizing your application. See [[User authorization]].
* API bringback URL: See [[Bringback url]].
* Notes: Private notes for the Safe Creative Team in order to obtain the activation of the keys
* Notes: Private notes for the Safe Creative Team in order to obtain the activation of the keys


After some time you will obtain the activation of these keys, so you can use the Safe Creative API (you will be notified by email).
After some time you will obtain the activation of these keys, so you can use the Safe Creative API (you will be notified by email).
Once you have obtained an API key, you can manage your API keys from the ''Applications'' tab on your [https://www.safecreative.org/myaccount/tab/USERKEYS_AUTHS Safe Creative account]
Once you have obtained an API key, you can manage your API keys from the ''Applications'' tab on your [https://www.safecreative.org/myaccount/tab/USERKEYS_AUTHS Safe Creative account]


Line 60: Line 59:
* '''sharedkey''' is the key assigned to the application. It has an associated private key.
* '''sharedkey''' is the key assigned to the application. It has an associated private key.
* '''locale''' is used to translate some messages to the specified locale. Locale format is language-country-variant, e.g. en-US
* '''locale''' is used to translate some messages to the specified locale. Locale format is language-country-variant, e.g. en-US
** Currently, only English (''en'') and Spanish (''es'') locales are supported. All other locales default to English.
* '''ztime''' is the number of milliseconds since January 1, 1970, 00:00:00 GMT (see [[ztime parameter]]). You can use the [[ztime component]] to retrieve the server ztime for synchronization
* '''ztime''' is the number of milliseconds since January 1, 1970, 00:00:00 GMT (see [[ztime parameter]]). You can use the [[ztime component]] to retrieve the server ztime for synchronization
* '''authkey''' is the user authorization for the application to use his account. It has an associated private key.
* '''authkey''' is the user authorization for the application to use his account. It has an associated private key.
* '''signature''' is a hash of the request computed using the private key associated to the sharedkey or authkey (depending on the component being called). See [[signature parameter]].
* '''signature''' is a hash of the request computed using the private key associated to the sharedkey or authkey (depending on the component being called). See [[signature parameter]].
* '''format''' specifies the response format: xml (default) or json
* '''format''' specifies the response format: xml (default),json or [[jsonp]]


Read the [[API reference]] to know the parameters expected by each component. Non-required parameters can be omitted from a component call.
Read the [[API reference]] to know the parameters expected by each component. Non-required parameters can be omitted from a component call.
Line 74: Line 74:


Some operations do not require a signature, so you can avoid calculating and sending it. The same can be said for the ztime
Some operations do not require a signature, so you can avoid calculating and sending it. The same can be said for the ztime
= Request signature =
See [[Signature parameter]]
Many operations require a signature of the request. This signature is the SHA-1 hash of the arguments, sorted by key, and preceded by a private key.
The private key to use depends on the component being called. If the component requires an authkey, then the private key to use is the one associated to that authkey. In other cases, you must use the private key associated to your shared key.


= User authorization =
= User authorization =
Line 82: Line 90:


You create an authkey with [[authkey.create]]. Then you must redirect your user to the user authorization page, where he must complete the authorization process. Once authorization is complete, user will be redirected to you user bringback URL.
You create an authkey with [[authkey.create]]. Then you must redirect your user to the user authorization page, where he must complete the authorization process. Once authorization is complete, user will be redirected to you user bringback URL.
= Nonce key =
See [[Nonce key]]
Some API operations require additional security through the use of a one-time nonce key.


= Callbacks =
= Callbacks =
Line 87: Line 101:
See [[API callbacks]]
See [[API callbacks]]


The API server will use your callback URL to send your application several notifications.
The API server will use your callback URL to send to your application several notifications.


= Error handling =
= Error handling =
Line 93: Line 107:
See [[Error handling]]
See [[Error handling]]


Invalid parameters or requests return an error, server-side problems return an exception.
Invalid parameters or requests return an error, identified by a fixed errorId. Server-side problems return an exception.
 


= Paginated responses =


See [[Paginated responses]]


* [[Error handling]]
Some requests returns paginated lists. Use the '''page''' parameter to get different pages of the list.
* [[About users]]
* [[About Works]]
* [[User management]]
* [[Building common URLs]]
* [[Paginated requests]]
* [[API Arquitecture]]


= See also =
= See also =
* [[API reference]]
* [[API Reference]]
* [[How to]]
* [[How to]]
* [[Troubleshooting]]
* [[Troubleshooting]]

Latest revision as of 11:32, 20 April 2022

API architecture

API architecture

Safe Creative API is a REST-like interface to Safe Creative services. It is stateless and is divided in 3 main areas

  • Core: Main services accessible through http://api.safecreative.org
  • Upload: API for uploading works, accessible through several dedicated upload servers (see work.upload.lookup)
  • Search: Public services for searching works

There are three trust levels for applications using Safe Creative API

  • Public API: Anyone can use these services without any previous requirement. These services allow access to public registration information, as if visiting the web site.
  • Standard API: This comprises the bulk of Safe Creative services. You need an application key to access these components. Usually a user's authorization key is also needed.
  • Partners API: Some components are reserved for use by Safe Creative partners. Contact community@safecreative.org if you want to become a partner.

See also:

Obtaining the keys to use the API

You must have a Safe Creative Account to use the API. You can create your API key at https://www.safecreative.org/new-api-key You will fill a form with some data that Safe Creative reviews in order to make the final authorization to use the application key:

  • Name: Name of the application that will use the Safe Creative API, it's a public name shown when an authorization to the user is made
  • Shared key: Provided shared key used to identify the applications calls
  • Private key: Provided private key to sign some API requests
  • Description: Public description of the service provided by the application
  • Web site: Public URL of the site of the application
  • API callback URL: Private URL used by Safe Creative to notify different types of events. See API callbacks
  • API bringback URL: See Bringback url.
  • Notes: Private notes for the Safe Creative Team in order to obtain the activation of the keys

After some time you will obtain the activation of these keys, so you can use the Safe Creative API (you will be notified by email).

Once you have obtained an API key, you can manage your API keys from the Applications tab on your Safe Creative account

Arena sandbox environment

There is a testing environment available at http://arena.safecreative.org.

This is a complete replica of the Safe Creative web site, including an API server. You can create user accounts, register works and request API keys.

It is strongly encouraged to use the arena environment for testing the API before using your application on the real service. To do so, you must request your application key at https://arena.safecreative.org/new-api-key instead. Arena application keys are immediately activated, so you can start testing the API as soon as you want.

As a matter of fact, API keys for production environment will not be activated if the application has not been previously tested against the arena environment

Accessing the API

Safe Creative API Web Services are accessible via a REST-like interface. The interface is rooted at http://api.safecreative.org/v2/ for production services and http://arena.safecreative.org/v2/ for the arena environment.

All requests must be done using the UTF-8 charset (HTTP request charset should be UTF-8). Responses are formatted as UTF-8 XML. It is strongly recommended to use HTTPS instead of HTTP. Some methods are required to be called using HTTPS.

Parameters

Parameters can be sent by POST or GET. You can mix POST and GET parameters. Some operations must send xml parameters that are best suited for POST method, but this is not required.

There are some common parameters: locale, sharedkey, ztime, authkey, signature, component and format

  • component is the name of the method or function to execute
  • sharedkey is the key assigned to the application. It has an associated private key.
  • locale is used to translate some messages to the specified locale. Locale format is language-country-variant, e.g. en-US
    • Currently, only English (en) and Spanish (es) locales are supported. All other locales default to English.
  • ztime is the number of milliseconds since January 1, 1970, 00:00:00 GMT (see ztime parameter). You can use the ztime component to retrieve the server ztime for synchronization
  • authkey is the user authorization for the application to use his account. It has an associated private key.
  • signature is a hash of the request computed using the private key associated to the sharedkey or authkey (depending on the component being called). See signature parameter.
  • format specifies the response format: xml (default),json or jsonp

Read the API reference to know the parameters expected by each component. Non-required parameters can be omitted from a component call.

URL syntax

API calls usually have the following format:

http://api.safecreative.org/v2/?component={component}&parameter1=value1&parameter2=value2&ztime={ztime}&signature={signature}

Some operations do not require a signature, so you can avoid calculating and sending it. The same can be said for the ztime

Request signature

See Signature parameter

Many operations require a signature of the request. This signature is the SHA-1 hash of the arguments, sorted by key, and preceded by a private key.

The private key to use depends on the component being called. If the component requires an authkey, then the private key to use is the one associated to that authkey. In other cases, you must use the private key associated to your shared key.

User authorization

See user authorization

In order to register works for a user, you need that user's authorization. User's authorizations are represented by an authkey.

You create an authkey with authkey.create. Then you must redirect your user to the user authorization page, where he must complete the authorization process. Once authorization is complete, user will be redirected to you user bringback URL.

Nonce key

See Nonce key

Some API operations require additional security through the use of a one-time nonce key.

Callbacks

See API callbacks

The API server will use your callback URL to send to your application several notifications.

Error handling

See Error handling

Invalid parameters or requests return an error, identified by a fixed errorId. Server-side problems return an exception.

Paginated responses

See Paginated responses

Some requests returns paginated lists. Use the page parameter to get different pages of the list.

See also