iScriba API
The iScriba API is another way to access your data from iScriba — it allows third party tools to easily interact with the service. This guide will provide you with everything you need to implement applications that works with iScriba.
The iScriba API tries as much as possible to follow the REST conventions. Thereby methods to retrieve data require a GET request. Methods to send data require a POST request. Modifications require a PUT request, and deletions require a DELETE request. If your HTTP client is not able to do request of PUT and DELETE type, you can use a request of POST type and specify a _method field.
The Terms of Service cover acceptable use of the service and its API (please pay particular attention to Section 8: Special conditions for developers). Beyond the legal aspects, we ask you to develop your applications with consideration — clients are required to comply with the HTTP 1.1 protocol, to “cache” as much as possible, to limit the frequency of requests, and to include a User-Agent header. If you encounter a bug with the service or the API, please give us a chance to fix it before going public. If you have any questions or problems, do not hesitate to contact the support.
Audience
This guide is intended for Web developers who have access to an account for which iScriba API is enabled.
These developers must have knowledge in a programming language such as PHP, .NET, Python, Perl, Ruby, Javascript or experience in the use of Web services.
Notational conventions
Throughout this documentation, you will find the following notational conventions:
- #{expression}
- Must be replaced by the value of the expression. For example : /#{user_id} should be replaced by /12345 (assuming user_id = 12345).
- [/argument/#{value}]
- Indicates an optional argument in the URI.
- ...
- For conciseness, we have omitted parts of the repetitive response.
- <!—comment—>
- Optional comment for clarification. The real answer does not contain a comment.
Responses format
The default response format is XML. However, you can get responses in different formats:
- by adding the argument /format/#{format}
- by specifying an Accept header: #{format}
- by adding an extension to the end of an URI .#{format}
The following responses format are available:
- xml
- json
- jsonp (allows you to specify a “callback” function by passing the argument /callback/#{my_function})
- serialize
- php (raw data that can be used with eval())
Error types
- 400 - Bad Request
- The request is not formatted properly or parameters are missing. Make sure you have not forgotten a required parameter.
- 401 - Access Denied
- You are not authenticated. Verify that your authentication token is correct.
- 403 - Forbidden
- You have exceeded the maximum number of requests, the API is not enabled for the account or you have exceeded the limit for your plan.
- 404 - Not Found
- The requested resource is not available.
- 406 - Not Acceptable
- Format requested is not available.
- 500 - Server Error
- There is a problem with the server. Try again after a few minutes and contact support if the problem persists.
- 501 - Not Implemented
- The requested resource does not exist.
- 502 - Bad Gateway
- The API is not available or is being updated.
- 503 - Service Unavailable
- The API is not able to respond to your request for capacity reasons. Try again later.
Rate limiting
We have set limits of request per method, per user and per hour to avoid unnecessary load on our servers. When this limit is exceeded iScriba sends a HTTP status code 403 Forbidden.
We urge you to make your applications conforming to this limitation.
When you are receiving a response, you have the ability to get rate limiting status with the following headers:
X-FeatureRateLimit-Limit: 100 <!-- limit per hour for the method --> X-FeatureRateLimit-Remaining: 99 <!-- number of remaining requests --> X-FeatureRateLimit-Reset: 1277234708 <!-- the date when the limit will be reset (in seconds) -->