Overview

How to use the API 'Try It' feature

8min

The "Try It!" feature allows you to run sample requests directly from the browser and view an actual response from the endpoint. In this topic, we show you how to use the feature using the Create Entity Type endpoint. For more information about Entity Types, see Entity.

Prerequisites

To use the "Try It!", you must first create an account in the OS1 Platform Developer Portal and register an App. For more information about creating an account, see Getting started with the OS1 Platform (Previous Version)ο»Ώ. For more information about registering an App, see Getting started with building Appsο»Ώ.

Setting up the Base URL

In the URL field, select base_url and enter the Tenant URL of the App you registered.

Document image
ο»Ώ

API Authentication

Service (backend) Apps on the OS1 Platform APIs use an access token to authenticate with the platform. You can use the Client ID and Client Secret of the App that you registered to generate an access token for testing purposes.

Generate an access token

To generate an access token use the Client Credentials Grant Tokenο»Ώ endpoint. Enter the following body parameters and headers to make a request:

  • clientId
  • clientSecret
  • X-COREOS-REQUEST-ID: Enter a unique random identifier. For example, request123.

πŸ”‘ Client ID and Secret

You will get the Client ID and Secret after registering an app on OS1 Platform Developer Portal. For more information about registering an App, see Getting started building Apps.

ο»Ώ

Select 'Try It!' to request the access token.

Document image
ο»Ώ

Access Token Expiry

The access token has an expiry date. If after running an API, it says the token is expired, you can simply generate a new one by following the steps mentioned previously.

Using the 'Try It' feature

The next step is to choose an endpoint from the left-hand side navigation and start to build your request. Here, we will try out the Entity Type.

Step 1: Enter path parameters

  • appId: This is the ID of the app. It is a string of 1 to 64 characters in length. Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_:-]{0,63}. For testing, you can use testapp1.
Document image
ο»Ώ

Step 2: Enter required body parameters

  • name: plural: Plural name of Entity Type. For testing purposes, enter a string of 1 to 16 characters in length. Pattern: ^[a-zA-Z0-9]{1,16}$. For example, vehicles.
  • name: singular: Singular name of Entity Type. For testing purposes, enter a string of 1 to 16 characters in length. Pattern: ^[a-zA-Z0-9]{1,16}$. For example, vehicle.
Document image
ο»Ώ

Step 3: Enter the required headers

  • X-COREOS-REQUEST-ID- Enter a unique random identifier. For example, request123.
  • X-COREOS-TID- The Tenant ID you got after creating the App on OS1 Developer Portal.
  • X-COREOS-ACCESS- The access token generated using the client ID and secret.
Document image
ο»Ώ

Step 4: Run the endpoint

To run the endpoint, select β€˜Try It’.

Document image
ο»Ώ

The response is displayed below the request example.

πŸŽ‰ You are now ready to explore other areas of the OS1 Platform APIs.