Data Studio @ Science Park | Data Publishers
15867
page,page-id-15867,page-template-default,ajax_fade,page_not_loaded,,qode-title-hidden,qode-child-theme-ver-1.0.0,qode-theme-ver-9.5,wpb-js-composer js-comp-ver-4.12,vc_responsive

Getting Started

What should I prepare before publishing an API?

Firstly, you have to host your data on your server and expose an endpoint either in HTTP, HTTPS or SOAP. Second, you have to prepare a request and response definition document describing the way to call your endpoint (e.g. what are the parameters needed) and describing the way to read the response (e.g. what are the fields to be returned).

When you have the endpoint and documentation ready, you are ready to sign-up a publisher account (or login to your publisher account if you have one) to start contributing your data to the data portal.

What are the types of endpoint that can be published?

Currently, we support endpoints in HTTP/HTTPS with JSON and XML as output. We also support endpoints in SOAP with XML as output.

How to sign-up for a publisher account?

You can sign-up a publisher account on the data portal. Your request will be routed to the administrator for approval. After approval, you will receive a notification email to confirm your account.

How to publish an API?

There is a 3-step wizard to publish an API.

 

In Step 1, you have to provide the general details like:

 

  • Name: This is the name of the API developers will see
  • Context: This is the context path the developers will see in the request URL
  • Version: This is the version of the API
  • Thumbnail: This is the thumbnail image developers will see
  • Description: This is the description of the API developers will see
  • API definition: This is the resource you are going to create. You can define multiple API resources here. For each API resource, you can define the parameters needed and also the method that will be used (e.g. GET, POST, etc)
step1

In Step 2, you have to provide the endpoints details like:

 

  • Endpoint Type: There are different endpoints types available

 

    • HTTP endpoint: A REST service endpoint based on a URI template.
    • Address endpoint: The direct URL of the service.
    • Failover group endpoint: The endpoints that the service tries to connect to in case of a failure. This happens in a round robin manner.
    • Load balance endpoint: The endpoints to which incoming requests are redirected to in a round robin manner. They automatically fail-over as well.
    • Default endpoint: The default endpoint sends the message to the address specified in the To header.

 

  • Production Endpoint: Specify the endpoint URI here
step2-1

In Step 3, you have to provide some further configurations like:

 

  • Make this the default version: A default API can be invoked without specifying the version number in the URL. For example, if you mark http://host:port/youtube/2.0 as the default version when the API has 1.0 and 3.0 versions as well, requests made to http://host:port/youtube/ get automatically routed to version 2.0.

 

  • Enable hard throttling limits: Check to enable hard throttling limits for the API as a way to protect your server from excessive requests. For example, if you know the capacity of your server can support 100 requests per min, you shall set a throttling limit that is lower than this rate (e.g. 60 requests per min) and then data portal will control the maximum number of requests calling your endpoint lower than this number.

 

  • Response cache: Enable this if you want the data portal to create a short-term cache for you. It is recommended that you can set the response cache as 10% of your update frequency. For example, if your request updates every hour, you can set the response cache as 6 minutes. So, data portal will cache the data once every 6 minutes and this lowers the requests generated to the endpoint and minimizes the time window to return stale data. If you disable this option, every request made from the developer will be translated into a call in real time to the endpoint.

 

  • Basic Information: You can fill up the business contact and technical contact for this API.
step3

When you have finished all the steps, you will be prompted with a congratulation dialog box as in below.

congrat
How to browse and maintain an existing API?

After you have created the API, you can browse the API by navigating the top menu. You shall see the below screen if you have chosen to view a particular API. You can see the below tag pages:

 

  • Overview: List out all the high-level information about the API
  • Lifecycle: List the current API status and the actions to convert to other status
  • Docs: List out all the documents related to the API. You can create request and response definition and sample data here.
  • Users: List out all the users who are subscribing to the API.

 

If you would like to edit the API, click “Edit” at the top.

info_page_read_only
What is the lifecycle of an API?

In the Lifecycle tab on the API page, you can find the screen below. There is a lifecycle related to an API with these statuses:

 

  • CREATED: API metadata is saved, but it is not yet visible to developers yet.
  • PUBLISHED: API is visible to developers.
  • DEPRECATED: API is still visible to developers and is available at runtime to existing subscribers (important note: when you have deprecated the API, you cannot reverse the action).
  • RETIRED: API is unpublished and becomes not visible to developers. Can be downgraded from DEPRECATED (important note: when you have retired the API, you cannot reverse the action).
  • BLOCKED: Access is temporarily blocked. Runtime calls are blocked and the API is not visible to developers.
info_page_lifecycle
How to upload the request and response definition and sample data?

In the Docs tab on the API page, you can find the screen below. You can specify fields below:

 

  • Name: This is the name of the document (e.g. Request and Response Definition, Sample Data)
  • Summary: A short summary about the document (optional)
  • Type: The type of document (e.g. How To)
  • Source: Whether the source is something inline or an URL or a File
info_page_docs_add_doc

For example, the below screen shows that the API is created with a “Request and Response Definition” document and also a “Sample data” document.

info_page_docs

When the developer is viewing the API, the documents can be found at the bottom of the “Documentation” tab.

info_page
Where can I find the list of developers using the API?

In the Docs tab on the API page, you can find the screen below. This screen shows the developers who are currently subscribing the API.

info_page_users
How can I know the API usage?

You can find a wide range of report in “Statistics” in the top menu.

publisher_report