Skip to main content

API Versions

The Showpad API is an essential backbone for integrating services, third-party applications, and digital devices.

In our onging efforts to provide the most reliable and stable environment, as well as address a broader collection of needs, this API currently has two versions: v3 and v4.

tip

Both versions work in hybrid mode so you can combine them to serve your needs.

API v3​

This is our most complete version. There are no plans to deprecate this version, however, we will not be implementing further updates to it. The API v3 reference contains the full details about this version.

Deprecated Endpoints

Some endpoints that are marked as deprecated in this version remain functional but are no longer updated. In most cases, you will find an equivalent endpoint in v4.

API v4​

This is our newest version. This version's growth is ongoing. Check out the API v4 reference for the full details about this version.

Key Features​

FeatureDescription
New resources and propertiesIn this API, we've introduced 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.
Optimized upload flowIn 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 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 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.

Migrate Versions​

note
Authentication is handled via v3

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

  • Users (partially)

  • Tags

  • Divisions

  • 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 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.

    OperationDescription
    Create an assetThis 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 fileThis 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 assetYou can use API v4 to add an author or locale properties to an existing asset. You can do this by using the UPDATE call.