API Fundamentals
An API (application programming interface) is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST (Representational State Transfer) architectural style.
Data Format
All data created, updated, or retrieved via the Showpad APIs must be in JSON encoded with UTF-8.
Requests
In a basic REST API setup, a client sends an HTTP request to the Showpad server, which processes it and answers with an HTTP response.
HTTP Methods
Showpad uses the following HTTP methods to map CRUD (Create, Retrieve, Update, Delete) operations to HTTP requests.
Method | Description |
---|---|
GET | Retrieves the representation of a single resource or a list of resources. |
HEAD | Same as GET , but without the response body. |
POST | Creates or updates an instance of a resource. |
PUT | Updates or replaces an existing resource. |
DELETE | Deletes an instance of a resource. |
Query Parameters
You can include parameters in your requests to control the returned data. Query parameters are attached to the end of the URL path. The following parameters are available for most Showpad APIs:
Parameter | Request Type | Description | Example |
---|---|---|---|
limit | GET ResourceLink Collection | Limits the number of retrieved resources. | A limit of 25 will only return 25 resources. |
offset | GET ResourceLink Collection | Offsets the retrieved Resource Links. | An offset of 3 will skip the first three results. |
fields | GET Resource or GET ResourceLink Collection | A comma separated list of attributes to be returned in the response. Typically used to make the response lighter. | Specifying id as a field parameter would retrieve a collection containing only ids . |
Response Codes
Showpad uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error based on the information provided in the request. Errors can be caused by many factors, such as invalid parameters, authentication errors, and rate limits.
2xx Codes
Code | Name | Description | Example |
---|---|---|---|
200 | OK | The request was successful. | GET /users.json will return a collection of user links. |
201 | Created | The resource was created. | POST /users.json (if the data entered was valid). |
4xx Codes
Code | Name | Description | Example |
---|---|---|---|
400 | Bad Request | The request is malformed. | |
401 | Unauthorized | The request lacks valid authentication credentials. | An incorrect or expired OAuth2 access token was sent. |
403 | Forbidden | The request uses credentials that are not authorized for access. | Divisions are only accessible by division-enabled organizations. |
404 | Not Found | The requested resource could not be found. | Specifying an non-existent ID. |
405 | Method Not Found | Returned when an invalid HTTP method is used. | POST /tickets.json is unsupported. |
409 | Conflict | The request conflicts with the current data. | Creating a user with a non-unique username. |
429 | Too Many Requests | Too many requests have been sent within a specific amount of time. |
5xx Codes
Code | Name | Description | Example |
---|---|---|---|
500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. |