Fetching your API documentation with the management API - Cloud

Talend Cloud API Designer User Guide

Version
Cloud
Language
English (United States)
Product
Talend Cloud
Module
Talend API Designer
Content
Design and Development > Designing APIs

Use the Talend Cloud API Designer management API to fetch your API definition in the API Portal Content format and add it to your repository.

Before you begin

Procedure

  1. Use the following command with the relevant parameters to get the API in the correct format:
    curl -X GET -H "Authorization:Bearer {userToken}" https://apid.{region}.cloud.talend.com/api/v1/api-definitions/{api-id}?format=ApiPortalContent
    Parameter Value
    {userToken} Token generated from Talend Cloud.
    {region} Region for your Talend Cloud account. The value can be:
    • us-west
    • us
    • eu
    • ap
    • at

    For more information, see Talend Cloud regions and URLs.

    {api-id} ID of the API version to fetch. To get it, open your API in Talend Cloud API Designer and go to Settings > MANAGEMENT API or use the GET method on the /api-definitions endpoint to get a list of API definitions with their IDs.
  2. Copy the response to the command.
  3. In your API Portal repository, open the apis folder.
  4. In apis, create a folder with the name of your API, and in that folder create a new folder with the version name.

    Example

    If you have an API named Contacts API in version 4.0.0, the folder structure should look like this: /apis/contacts-api/4.0.0/.
  5. Create a file named index.md in the version folder and paste the response to the command in it.

    Example

  6. Optional: If you also want to provide API definitions that your users can download, use the same command with the format OpenApi3 or Swagger20, then save the response content as openapi30.json or swagger20.json in the same folder as the documentation.
  7. Commit your changes.

Results

Your API documentation is now ready to be published. You can repeat these steps for any other APIs that you want to include in your portal.