Skip to main content

Intro to Showpad API v4

The Showpad API is an essential backbone for integrating services, third-party applications, and digital devices. To better serve our community of developers, we’re upgrading our API to address a broader collection of needs. We are introducing a new subset of our existing Showpad API v3 to improve the experience for developers.

note

Both versions, Showpad API v3 and v4, work in hybrid mode. This means you can combine them to serve your needs. However, while Showpad API v3 still works, we will not be implementing further updates.

Benefits of Showpad API v4​

New resources and properties​

In this new API, we're introducing some new properties on the Asset object to make automation around these properties easier. The most important ones are:

  • Author defines who manages and owns what content. You can assign one or more authors to an asset.
  • Locale allows localization of the content in a Showpad organization. Assign countries and languages to an asset.
  • Tag categories define the organizational structure of tags. It allows multiple levels and bulk editing of tags.

Check out the API Reference for the exact details.

Optimized upload flow​

In Showpad API v3, creating and uploading assets is more complicated and uploading is slower. When an asset is processed, a ticket ID is returned. This ID polls our platform to find out whether the processing was successful.

  • If successful, you receive an asset ID that is required to start working with the asset like, for example, assigning tags.
  • If not successful, the whole process restarts.

Processing time depends on the size and type of asset. This makes the duration unpredictable, forcing you to create a polling mechanism that covers a large period of time. Multiple API calls are needed that might be unnecessary.

However, in Showpad API v4, this ticket mechanism is greatly improved. The asset is created immediately and processing is done asynchronously. The call itself has been revised and allows sending all asset properties in one go, including tags.

The Showpad API v4 subset also introduces an improved upload mechanism for your binary files. Whenever an asset is created, you can use the asset ID to retrieve an upload URL. This is an upload location on AWS. This approach takes your location into account and selects a storage server that is the closest for you, ensuring faster speeds.

Check out the Asset Management guide on how to use these new APIs.

Upgrade from v3 to v4​

The migration impacts you if you currently use the following v3 calls.

  • Assets
    • POST /assets.json (Create an asset item)
    • POST /assets/{id}.json (Update an asset item)
    • POST /assets/{id}/tags.json (Add a tag to an asset item)
  • Users (partially)
  • Tags
  • Divisions
note

Authentication happens via the existing v3 call.

Assets​

In Showpad API v4, the creation of an asset requires you to use two API calls, i.e. one call to create the asset and one call to upload the actual (binary) file. When you create the asset, you get an ID immediately and you can manage whatever you want on that asset. The actual binary file upload (and processing) is handled by a separate call.

In Showpad API v3, creating an asset in Showpad was done via a ticket ID. The ticket ID allowed you to poll the processing of the asset. Once processing was successful, you would get an asset ID. After that, you could start managing the asset attributes, like adding tags. We moved away from this process, as processing time of an asset is unpredictable.

Create an asset​

This call can be used to create the asset record and manage its metadata. The details of the call can be checked here.

Create an asset file​

This call is used to upload the binary data for an asset. Based on the asset ID you can retrieve an upload URL and content type. In order to upload the file, you need to leverage a PUT request, using the correct content type in the header and the actual binary file in the body.

All info on this call can be checked here. Here you can check how to upload the actual file.

Updating an existing asset​

You can use Showpad API v4 to add an author or locale properties to an existing asset. You can do this by using the UPDATE call.

Authentication​

Authentication is exactly the same as in Showpad API v3. This makes it also easy to leverage both Showpad API v3 and v4 in a hybrid mode. This is mainly important for customers who use Showpad API v3 today and want to leverage Showpad API v4 for a subset of their needs (e.g. to add an author to a file).