Templafy Public API

This article contains the release notes for the Stable version of the Templafy Public API.

Templafy Public API V3

The following endpoints and related functionality were delivered as a part of the third Stable version.

Spaces

• GET endpoint returns all existing active spaces. The identifier of a retrieved space can be used later to query the libraries.

Improvements released December 2024

We now return additional information if the DELETE APIs on data sources fail. For the APIs below, we return status code 423 to indicate that the resource is locked and cannot be deleted. In addition we return the lock reason, which can be restrictedAccess or hardDependency. The reason restrictedAccess means that either the data source is a system data source and cannot be deleted, or the system has locked the resource temporary to take an action. If the reason is hardDependency we return a limited list of the resources that are depending on the resource and therefore, prevent the resource from being deleted.

• DELETE /data-sources/{dataSourceId}/fields/{fieldId}.
• DELETE /data-sources/{dataSourceId}/items/{itemId}/fields/{fieldId}.
• DELETE /data-sources/{dataSourceId}/items/{itemId}.
• DELETE /data-sources/{id}.

Templafy Public API V2

The following endpoints and related functionality were delivered as a part of the second Stable version.

Templates and assets

For Documents, Presentations, Spreadsheets, and Text elements libraries the following was added:

• POST to generate a compiled document based on the template:
  • With a valid email address, the system will look for the default user profile related to the user. If not valid the endpoint returns 401 error.
  • If template does not exist, the endpoint returns 404 error.
  • The support to produce a PDF file together with the Office file (not supported for Text elements assets).
  • The endpoint can receive external data that will be injected into the pipeline under Host system identifier.

Resources

A set of endpoints to manipulate data sources, data source fields, data source items and data source item fields.

Data sources

This set of endpoints enables manipulation of data sources. There is a possibility to retrieve one or more data sources, and to create, update or delete a data source.

• GET a list of all data sources and the schema of their fields.
• GET a single data source and the schema of its fields.
• POST endpoint to create a new data source using the submitted field schema. This endpoint is polymorphic as it accepts different properties based on the data source field type (text, number, image, reference). Each data source needs to have a unique name. A single tenant can have up to a 1000 data sources.
• PATCH endpoint to update a single data source.
• DELETE endpoint to delete an existing data source.

Data source fields

This set of endpoints enables manipulation of data source fields within an existing data source.

• GET a schema of a single field from an existing data source.
• POST endpoint to create a new field within an existing data source. Also a polymorphic endpoint, accepting details about text, number, image or reference field. A single data source can have up to a 300 fields.
• PATCH endpoint to update a single data source field.
• DELETE endpoint to delete an existing data source field.

Data source items

These endpoints provide a functionality to manipulate items of a data source.

• GET a list of all data source items from an existing data source using paging.
• GET a single data source item from an existing data source.
• POST endpoint to create a new data source item within an existing data source. A polymorphic endpoint, supporting text, number, image, reference, color theme and font field types. A single data source can have up to a 50000 items.
• PATCH endpoint to update a data source item. Also polymorphic, supports same field types as POST endpoint.
• DELETE endpoint to delete an existing data source item.

Data source item fields

These 2 endpoints help with manipulating individual fields of a data source item.

• PUT endpoint to update a single field on an existing data source item. A polymorphic endpoint, supporting text, number, image, reference, color theme and font field types.
• DELETE endpoint to delete a single data source item field.

Improvements released December 2024

We now return additional information if the DELETE APIs on data sources fail. For the APIs below, we return status code 423 to indicate that the resource is locked and cannot be deleted. In addition we return the lock reason, which can be restrictedAccess or hardDependency. The reason restrictedAccess means that either the data source is a system data source and cannot be deleted, or the system has locked the resource temporary to take an action. If the reason is hardDependency we return a limited list of the resources that are depending on the resource and therefore, prevent the resource from being deleted.

• DELETE /data-sources/{dataSourceId}/fields/{fieldId}.
• DELETE /data-sources/{dataSourceId}/items/{itemId}/fields/{fieldId}.
• DELETE /data-sources/{dataSourceId}/items/{itemId}.
• DELETE /data-sources/{id}.

Templafy Public API V1

The following endpoints and related functionality were delivered as a part of the first Stable version.

Libraries

Two GET library endpoints to fetch the data about all libraries from all spaces or any specific library. The response will contain, but not be limited to, the space identifier, the library type, and the root folder identifier. These will be required to be passed when making calls to other endpoints. The current version of API doesn't support returning space names.

Folders

Five endpoints to work with folders. They are as follows:

• GET folder by the folder identifier to return the basic information including the navigation path and the parent folder identifier.
• GET the list of any children's folders by the parent folder identifier.
• POST endpoint to create a new folder with the specified name.
• PATCH the folder to update the name and/or move to a different parent folder within the same library across all spaces. The endpoint supports partial updates.
• DELETE the folder with all content inside. The root folders can't be deleted.

Templates and assets

Every template and asset library supports five endpoints. All the endpoints across all libraries use the same route structure that only differs by the library type and request/response contracts. In the sections below only the key features and main differences will be described. Please refer to Swagger documentation to get more detailed information.

Every library supports the following five endpoints:

• GET all the assets or templates from the specified folder. By default, the results are not paginated. To limit the results, the searchQuery parameter can be used to filter the template name, description, and tags. Page number and page size can be passed to dynamically go through the returned data.

• GET the asset or template by the identifier. The endpoint will return the asset/template details, external data, and the generated temporary access URL for content downloading.

• POST to create a new asset or template and return its identifier. For file-based assets/templates only the file is required to be passed, while the name is automatically retrieved. Some additional details might be passed as well as external data that are used to store any information for future reference.

• PATCH allows doing multiple actions with the asset or template.

  • Update asset/template details.
  • Replace asset/template file.
  • Move asset/template to a different folder within the library across spaces.

  This endpoint supports partial updates.

• DELETE the asset or template by the identifier.

Library specific details

• Images contain data about dimensions, automatic tags, and generated preview links.
• Links library being not file-based uses application/json content type for all its endpoints. Here for POST name and URL should be provided. PATCH can be used to change the details, URL, or move an asset.
• Presentations, Slide and SlideElements are the libraries that work with two types of assets at the same time, for example, requesting all data from the Presentation library will return both presentations and slides in a flattened structure. AssetType can be used as a discriminator to make a distinction. Both the identifier of the presentation or slide can be used to get the details about the asset. It will contain generated preview links, dimensions, and also type-specific data like childrenAssetIds for the presentation or presentationId for slide. There is a limited scope of actions that can be done on slides as a part of PATCH or DELETE.