API Fundamentals
The Showpad API is a RESTful client-server API. In its essence, the term REST is used to indicate the API is based on the principles of:
- Sending an HTTP request and receiving an HTTP response
- Using HTTP verbs (
GET,POST,PUT, etc.) - Interpreting HTTP response codes
- Resources
HTTP Methods
In a basic REST API setup, an HTTP request is sent to the Showpad server, which processes the request and answers with an HTTP response. The request itself has a number of parameters, important to the Showpad API. It supports the following HTTP methods to map CRUD (Create, Retrieve, Update, Delete) operations to HTTP requests.
| Method | Description |
|---|---|
GET | Used to retrieve resources of a collection of resource links |
POST | Used to create or update a resource |
PUT | Used to update a resource |
DELETE | Used to remove a resource |
HEAD | Used to retrieve resources of a collection of resource links |
Query Parameters
Query parameters are parameters attached to the URL after the path of the URL.
Depending on the type of request, there are a number of standard query parameters:
| Parameter | Type | Availability | Description |
|---|---|---|---|
limit | GET ResourceLink Collection | V1+ | Limits the number of retrieved resources (i.e. a limit of 25 will return 25 resources). |
offset | GET ResourceLink Collection | V1+ | Offsets the retrieved Resource Links (i.e. an offset of 3 will skip the first 3 results) |
fields | GET Resource or GET ResourceLink Collection | V1+ | A comma separated list of attributes to be returned in the response. It is usually used to make the response lighter. E.g. if you only want to find out the ID of resources in a collection, specifying id as a field parameter would only retrieve a collection of ids. |
HTTP Response Codes
| Code | Name | Description | Example |
|---|---|---|---|
200 | OK | Returned when a request successfully executed | GET /users.json will return a collection of user links |
201 | Created | Returned when a resource is created | POST /users.json (if the data entered was valid) |
400 | Bad Request | Returned when the request is invalid. This is a very general error. | |
401 | Unauthorized | Returned when an incorrect access token has been specified | An incorrect or expired OAuth2 access token was sent |
403 | Forbidden | Returned when the user does not have enough permissions to access the resource. | Divisions is only accessible by division enabled companies |
404 | Not Found | Returned when a resource is not found. | Specifying an non-existent ID is specified. |
405 | Method Not Found | Returned when an invalid HTTP method is used. | POST /tickets.json is unsupported |
409 | Conflict | Returned when the user has entered invalid data. | Creating a user with a non-unique username |
429 | Too Many Requests | Returned when the user exceeds the rate limit for a given time frame. | |
500 | Internal Server Error | Returned when a server error occurs. |