Showpad API concepts

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

The concepts of awesomeness

• 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

Resources and resource links

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.

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. On top of those, the Showpad API also supports the LINK AND UNLINK methods to create and delete relations between resources:

Request header

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.

Media types

In order to POST or PUT data to Showpad, 3 different content-types can be used.

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

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:

The number of total matches that corresponds to your request can be found in the “count” attribute.

"response":
 {
 "count": 29,
 "items": [...]
  }

Response headers

Following header fields are sent for every request.

HTTP Response Codes