API Overview

Introduction

Safe Creative API Web Services are accessible via a REST-like interface. The interface is rooted at http://api.safecreative.org/v2/ unless you are using the arena server that lives in the arena subdomain: http://arena.safecreative.org/v2/.

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
• ztime is the number of milliseconds since January 1, 1970, 00:00:00 GMT according to the API server. You can 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)
• format specifies the response format: xml (default) or json

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

• Zime parameter
• Signature parameter
• Obtain the keys to use the API
• User Key callback URL
• User Key bringback URL
• Authkey: The user authorization
• Error handling
• About users
• About Works
• User management
• Building common URLs
• Paginated requests
• API Arquitecture

API functions reference

Generic methods

• version
• ztime
• authkey.create
• authkey.state

User management

• user.link
• user.modify
• user.unlink

Master tables

• user.licenses
• license.features
• user.countries
• user.profiles
• work.types
• work.types.tree
• work.languages

Works info

• work.get
• work.get.private
• work.list
• work.certificate
• work.download
• work.download.private

Work management

• work.upload.lookup
• work.upload.begin
• work.upload.chunk
• work.upload.commit
• work.register
• work.attachfile
• work.delete

Multiauthorship

• work.rightsholders.add
• work.rightsholders.list
• work.rightsholders.remove

Search

• search.byquery
• search.byfields
• search.byhash
• semantic.query

How to

• Register work uploading
• Register work via URL
• Register work with extended info
• Register work with relations
• Desktop Applications

Troubleshooting

• Signatures
• Charsets
• Callbacks