Templafy Hive Swagger - How does it work?

About this article

Swagger UI is a documentation tool for REST APIs. Via Swagger UI, different API actions can be visualized and interacted with. This allows users to test the API without any implementation logic in place. This article will show how the Swagger UI of the Templafy Public API can be utilized to upload, replace and download a document in the Templafy document library using the Library Management endpoints. It contains the following sections:

• How to connect a Templafy tenant to the Swagger UI
• How to find the input parameters for API commands
• How to upload a document in the Templafy document library
• How to replace an existing document in the Templafy document library
• How to download a document from the Templafy document library

Prerequisites

How to connect a Templafy tenant to the Swagger UI  

1. Access the Templafy Swagger UI page via this link: https://api.templafy.com/
2. In the "Server variables" section, enter the name of your Templafy tenant in the "tenantId" field
3. In the "Server variables" section, navigate to the authorize button and enter your Public Library API Key 
4. Click authorize
5. Click Close

How to find the input parameters for API commands

In this example, a document will be uploaded, replaced, and downloaded from the Templafy document library. To execute the corresponding API commands, they need to be populated with parameters pointing it to the correct library, folder, or asset where the action should be executed.

SpaceId: With the spaceId, the API can identify the library space in which to execute the API command. There are two ways to retrieve the spaceId:

With the API:

1. In the Swagger UI, navigate to the "Spaces" section
2. Choose GET /spaces by clicking on the downwards arrow
3. In the parameters field, click Try it out to activate parameter input
4. Click Execute
5. From the JSON response, copy the SpaceId from the desired Space.
    

Through the browser developer tools:

1. Go into the admin center of your Templafy tenant 
2. Navigate to the library tab for which you would like to retrieve the spaceId
3. Navigate to any template library (documents, presentations or spreadsheets)
4. Open the developer tools (F12 for Windows, Cmd+Opt+J for Mac)
5. Refresh the page 
6. Click on any request that browses content (i.e. navigation path) 
7. Copy the spaceId from the Request URL 

FolderId: With the folderId, the API can recognize in which folder of the the Templafy library it needs to execute the given command. To get the folderId

1. In the Swagger UI, navigate to the "Libraries" section
2. From the available requests, choose GET /libraries/ {spaceId}/{librarytype} by clicking on the downwards arrow
3. In the parameters field, click Try it out to activate parameter input
4. Navigate to the parameters field and enter your spaceId
5. From the libraryType dropdown, choose the libraryType for which you would like to retrieve the Id
6. Click Execute
7. From the JSON response, copy the rootfolderId
8. Now, navigate to the "Folders" section
9. From the available requests, choose GET /libraries/{spaceId}/{librarytype}/folders/{folderId}/folders by clicking on the downwards arrow
10. Navigate to the parameters field and enter your spaceId as well as your rootfolderId
11. From the libraryType dropdown, choose the libraryType for which you would like to retrieve the Id
12. Click Execute
13. From the JSON response, copy the folderId of the folder in which you would like to execute your API command 

AssetId: With the assetId, the API can recognize for which asset in the Templafy library it should execute the given command. To get the assetId

1. In the Swagger UI, navigate to the asset section for which you would like to execute the API command. In this example, we want to work with Word documents and therefore navigate to "Documents"
2. From the available requests, choose GET /libraries/{spaceId}/document/folders/{folderId}/assets by clicking on the downwards arrow 
3. In the parameters field, click Try it out to activate parameter input
4. Navigate to the parameters field and enter your spaceId as well as your folderId
5. Click Execute
6. From the JSON response, copy the assetId of the document for which you would like to execute your API command

How to upload a document in the Templafy document library

1. In the Swagger UI, navigate to the "Documents" section
2. From the available requests, choose POST /libraries/{spaceId}/documents/folders/{folderId}/assets
   by clicking on the downwards arrow 
3. In the parameters field, click Try it out to activate parameter input
4. Navigate to the parameters field and enter your spaceId as well as the folderId of the folder you would like to upload the document into
5. In the request body field, click Choose File and select the file you would like to upload
6. Click Execute
7. Navigate to the response field and check the  "Server response". Code 201 indicates a successful upload

How to replace an existing document in the Templafy document library

1. In the Swagger UI, navigate to the "Documents" section
2. From the available requests, choose PATCH /libraries/{spaceId}/documents/assets/{assetId}
   by clicking on the downwards arrow 
3. In the parameters field, click Try it out to activate parameter input
4. Navigate to the parameters field and enter your spaceId as well as the assetId of the document you would like to replace
5. In the request body field, navigate to the "Name" tab. Either enter a new display name for the document, or, if you do not wish to rename the document, unselect the checkbox Send empty value
6. In the request body field, click Choose File and select the new document with which you would like to replace the existing document
7. Click Execute
8. Navigate to the response field and check the  "Server response". Code 201 indicates a successful replacement

How to download a document from the Templafy document library

1. In the Swagger UI, navigate to the "Documents" section
2. From the available requests, choose GET /libraries/{spaceId}/documents/assets/{assetId}
   by clicking on the downwards arrow 
3. In the parameters field, click Try it out to activate parameter input
4. Navigate to the parameters field and enter your spaceId as well as the assetId of the document you would like to download
5. Click Execute
6. From the JSON response, copy the downloadURL  
7. Open a new tab in your browser and paste the downloadURL
8. Click Enter on your keyboard to download the document to your PC

Related articles