API Standards
The Syniverse Developer Community provides RESTful APIs for you to do actions from your applications.
When making the API calls, the base Syniverse URI through which all calls are going through is https://api.syniverse.com/...
Please see each service offering for specific documentation on how to use the services provided.
For information on how applications are authenticated and authorized, please see the Security section.
HTTP Methods
This section describes the methods commonly supported within the Syniverse Developer Community, please see the specific service offering documentation for methods supported when using those services. For more information about methods please read RFC 7231, which defines the standard methods. Syniverse Developer Community, however, will only require support for a limited subset of these methods. The primary methods that we will support, and their intended usage, are as described in the following table.
| Method | Usage | IETF Reference |
|---|---|---|
| POST | POST is used to create or update an entity. POST differs from PUT as it can create or update a partial entity. Any attribute that is not specified in the 'POST' would be left as-is. | RFC 7231 Section 4.3.3 |
| PUT | PUT is used to update an entity. PUT method can also be used to create an entry; however, when using PUT to create an entity please use it with care. Unless specifically stated in the design of an API, PUT methods can only perform updates. Whether it is creating an entity or updating it, a 'PUT' must always provide the complete entity. Partials are not permitted. If a partial creation or update is required, use the POST method instead. | RFC 7231 Section 4.3.4 |
| GET | Used to retrieve an entity. | RFC 7231 Section 4.3.1 |
| DELETE |
DELETE requires that the entity be deleted from the server. The result of the DELETE call can be that the item is left on the server for tracking purposes, but cannot be retrieved or used by an API call or any other functionality.
DELETE should not be used in the following scenarios:
|
RFC 7231 Section 4.3.5 |
| HEAD | This method does the same as a GET, except that only the header is returned, and not the body. | RFC 7231 Section 4.3.2 |
| PATCH | PATCH method was introduced in RFC 5789, with the intent to allow a partial replacement of an entity. SDC doesn't support PATCH, please use POST instead | RFC 5789 |
HTTP Header Fields
For supported header fields please see the service offering documentation
API Responses
These are the standard responses you will receive, but for responses per service offering please see the documentation per each Service Offering.
API Success
| Code | Reason-Phrase | Description |
|---|---|---|
| 202 | Accepted |
Accepted. Response used when an action request has been accepted, but not yet completed.
Example: POST a request for a file to be processed. You receive accept for the file to be processed but the processing has not been completed at the time the response is sent back. |
| 200 | OK | General purpose response that the API call |
| 201 | Created | Used when an entity has been created by the POST or PUT methods |
API Failure
SDC will send a two tiered error information on failed API calls. First level is the standard http error code and the second level is the standard error object.
| Code | Reason-Phrase | Description |
|---|---|---|
| 304 | Not Modified | 'Update' requested but the item or entity could not be updated. Does not include failure in Optimistic Locking |
| 400 | Bad request | Something went wrong with the request. Usually this means that there is a parameter missing in the API call. |
| 401 | Unauthorized | Missing credentials |
| 403 | Forbidden | Credentials provided do not have the entitlements to perform the requested action. |
| 404 | Not Found | Requested resource not found |
| 405 | Method not allowed |
The HTTP method is not valid for the resource.
Example: used 'DELETE' on data that should have an end-date applied instead. |
| 409 | Conflict | Indicates that an update could not be completed due to a conflict with the current state of the resource. Includes failure in optimistic locking. |
| 412 | Precondition failed |
Error code provided when one or more of the conditions given in the header evaluated to "false" when tested on the server.
Example: Request made to retrieve the result of processing a file and processing is not yet done |
| 500 | Internal error | Server ran into an unexpected situation that prevented it from doing what was requested. |
| 501 | Not implemented | API referenced doesn't exist. |
| 503 | Service unavailable |
Server is currently unable to handle the request.
Reason: temporary overload, maintenance or too many requests |