The API is used to integrate with Digital Asset Management systems, user management and many more. The Showpad API Explorer allows you to try out the API and you can access it via the Online Platform in the Admin Settings. This article dives deeper into the world of the Showpad API and explains the various methods and parameters you can use.
Note: To access the API Explorer directly, go to https://{yourSubdomain}.showpad.biz/devportal/explorer
Key Features
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...)
- Interpreting HTTP response codes
- Resources
Note: The base URL for the REST API is /api/v{apiVersion}
You need this to succeed
This is what you need to build your first app that interfaces with the Showpad REST API:
- Showpad’s Ultimate pricing plan
- Access to Showpad Online Platform
- Basic Knowledge of REST
- Basic Knowledge of JSON
- Universal Resource Location (URL)
- Resources and resource links
- HTTP methods
- Request headers
- Media types
- Query parameters
- Response headers
- HTTP response codes
Universal Resource Location (URL)
The URL identifies which resource or collection of resource links you want to access. It is structured as follows:
/api/v{apiVersion}/{resource}[/{resourceId}[/{subResource}]][.json] |
Below are a number of examples:
- /api/v1/tags.json
- /api/v2/assets/12345.json
- /api/v2/users/12345/usergroups.json
A response from the Showpad API is based on the concept of resources and resource links. A resource is the central entity within the Showpad API. It is characterized by an ID, a type, a set of attributes and a set of relationships to other resources.
"response": { "id": "279386a847eb5802fc566cb773916d41", "resourcetype": "Asset", "name": "Showpad One Pager.pdf", .... "tags": { "href": "https://demo.showpad.biz/api/v3/assets/279386afc566cb773916d41/tags" }, "division": { "id": "4643adcc1621814e91c489b34bb428ed", "href": "https://demo.showpad.biz/api/v3/divisions/4643ae91c489b34bb428ed" }, |
An important characteristic of the resource is the type, identified by the field resourcetype. Every resource has this field and there are 12 resourcetypes, distributes over both the reseller and the company API.
Resource Type | Availability | Type |
---|---|---|
Apikey | V1 | Reseller + Company |
Asset | V1+ | Reseller + Company |
Comment | V1+ | Reseller + Company |
Contentprofile | V2+ | Company |
Division | V2+ | Company |
DivisionPermission | V2+ | Company |
Organisation | V1+ | Reseller |
TabletPermission | V2+ | Reseller |
Tag | V1+ | Reseller |
Ticket | V1+ | Company |
Usergroup | V1+ | Company |
User | V1+ | Company |
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.
Note: We will sunset the LINK AND UNLINK methods on April 1st, 2021.
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 |
LINK |
Used to establish a relationship between resources |
UNLINK |
Used to break an established relationship between resources |
HEAD |
Used to retrieve resources of a collection of resource links |
Header parameters are parameters attached to the header of the request. Besides the standard header parameters such as Content-Type, there are some header parameters specifically designed for usage in the Showpad API.
Parameter | Type | Version | Description | |||
---|---|---|---|---|---|---|
SHOWPADAUTHORIZATIONKEY |
|
All authenticated requests | V1 |
Each request needing authentication requires this header to be set. It contains the Showpad API key. Only applicable in API V1. |
||
AUTHORIZATION |
|
All authenticated requests | V2 |
Used for OAuth2 authenticated requests. It contains the OAuth2 access token in the following format: AUTHORIZATION: Bearer:myObtainedAccessToken Only applicable in API V2. |
||
LINK |
LINK, UNLINK and POST (create resource) requests | V1+ |
You can specify which resources should be linked/unlinked to the resource at hand by adding a parameter to the request. A relationship is specified as follows: LINK: <resourceID>; rel="RelatedResourceType" The use of this parameter is based on the draft IETF standard. You can add multiple relationships by delimiting this parameter by a comma. For example: LINK: <ID1>; rel="RelatedResourceType1", <ID2>; rel="RelatedResourceType2", <ID3>; rel="RelatedResourceType3" |
|||
X-HTTP-METHOD-OVERRIDE |
|
GET resource collection (e.g. /users) or GET resource (e.g. /users/{id}) requests |
Some API clients have difficulties sending requests with certain HTTP verbs such as PUT or LINK. In order to make those requests possible, the X-HTTP-METHOD-OVERRIDE parameter can be used to mimic a certain HTTP method, while keeping the rest of the parameters the same. For example: X-HTTP-METHOD-OVERRIDE: delete |
In order to POST or PUT data to Showpad, 3 different content-types can be used.
Header Field Name | Description |
---|---|
Content-type | application/www-url-encoded (PUT + POST) |
multipart/form-data (only POST) | |
application/json (PUT + POST) |
Notes:
- Application/www-url-encoded and multipart/form-data can only be used to add or update a single resource.
- Be aware that multipart/form-data is only valid for POST requests.
- Application/json can be used both to update single resource and create one or multiple resources.
- In order to create a single resource, you use a JSON key value array, whereas when you want to create multiple resources in batch, you use an array of JSON key value arrays.
Query parameters are parameters attached to the URL, usually after the path of the URL and this encoded as application/x-www-form-urlencoded. The example below shows 3 parameters: limit and offset.
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 Resource Links i.e. a limit of 25 will return 25 Resource Links | |||
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. 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 | |||
method | GET Resource or GET ResourceLink Collection | V1+ | Some API clients have difficulties sending requests with certain HTTP verbs such as PUT or LINK. In order to make those requests possible, the ‘method’ parameter can be used to mimic a certain HTTP method, while keeping the rest of the parameters the same. | |||
describe_model | All Requests | V1+ | Adds the Swagger model specification to the request | |||
describe_apis | All Requests | V1+ | Adds the Showpad API description to the request | |||
suppress_response_codes | All Requests | V1+ | Some API clients have their own way of processing HTTP response codes. E.g., some clients throw an exception when receiving a 40x of 50x, leaving no way to inspect the content of the response. Setting ‘suppress_response_codes’ to true, all HTTP response codes are set to 200 so the responses can more easy be inspected. In the ‘meta’ field of the response, the original response code is still mentioned so correct interpretation can still take place. |
The number of total matches that corresponds to your request can be found in the “count” attribute.
"response": { "count": 29, "items": [...] } |
Following header fields are sent for every request.
Header Field Name |
Description |
---|---|
access-control-allow-credentials |
Specifies which locations can participate in cross-origin resource sharing |
access-control-allow-headers |
Specifies which locations can participate in cross-origin resource sharing |
access-control-allow-methods |
Specifies which locations can participate in cross-origin resource sharing |
access-control-allow-origin |
Specifies which locations can participate in cross-origin resource sharing |
cache-control |
Caching instructions for the server. |
connection |
Control options for the current connection |
content-encoding |
The type of encoding used on the data, typically ‘gzip’ |
content-type |
The media type of this content, typically ‘application/json’ |
date | Date and time the message was sent by the server |
pragma | Caching instruction for the server, but for HTTP/1.0 client |
server | Name of the server |
transfer-encoding | Form of encoding used to safely transfer the entity to the user, typically ‘chunked’ |
x-content-type-options | Typically ‘nosniff’ |
x-frame-options | |
x-newrelic-app-data | |
x-ratelimit-limit | Number of requests you are allowed per day |
x-ratelimit-remaining | Number of requests left |
x-ratelimit-reset | Datestamp of date when your rate limit will be reset |
x-robots-tag | |
x-xss-protection |
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. |