Calling REST APIs

Authenticate and send a test API call to ensure that everything works correctly in your environment.

About this task

REST API usage for Environmental Intelligence is thoroughly documented in the IBM API Hub - Getting Started guide. Follow the guide in IBM API Hub to learn about how the REST APIs work within the platform, and to get up and running with calling REST APIs for each component.

Or, follow this task to quickly get started by authenticating with the platform and making a test call to ensure that your environment is set up correctly.

Authenticating with the platform

You must authenticate before you can call the REST APIs. To do so:

Go to the developer console and make note of your API key, Tenant ID, and Organization ID.
Authenticate with the platform.
- For all APIs except for GHG
  Use the IBM API Hub - Platform Authentication API to authenticate, or use Curl in the following step.
  If your REST client supports importing a Curl request, copy and paste the following request into your REST client, replacing the orgId, X-Api-Key, and tenantId values with your values from the developer console:
```
curl --silent --request GET \ --url 'https://api.ibm.com/saascore/run/authentication-retrieve/api-key?orgId=REPLACE_THIS_VALUE' \ --header 'X-Api-Key: REPLACE_THIS_KEY' \ --header 'X-IBM-Client-Id: saascore-<tenantId>'
```
  Your REST client sends a GET call to authenticate you and sends back a successful 200 OK response and token:
- For GHG APIs
Use Curl to authenticate in the following step. If your REST client supports importing a Curl request, copy and paste this request into your REST client, replacing the apiKey value with your API key:
```
curl --request POST --url https://auth-b2b-twc.ibm.com/Auth/GetBearerForClient \ --header 'Content-Type: application/json' \ --header 'cache-control: no-cache' \ --data '{"apiKey":"<API_KEY>", "clientId":"ibm-agro-api"}'
```
Your REST client sends a POST call to authenticate you and sends back a successful 200 OK response and token:
Review the response and make note of the access token.
As a result of the REST API call, you obtain an access token in the form of a JSON Web Token (JWT) using the HTTP Authorization header Bearer scheme value. For example, Authorization: Bearer JWT. Make note of the token's value in the response, as it is needed when calling REST APIs.
Note: After you authenticate with the platform, your JWT token is valid for 1 hour, so it can be reused for subsequent API calls until the time it expires.

Calling REST APIs

Use your access token obtained in the previous steps to make REST API calls in Environmental Intelligence.

Select the REST API that best suits your business needs and call it in your REST client, along with its required parameters and authentication.

Tip: IBM API Hub makes it easy to help form your API calls. If you are unsure of which parameters are required, use Generate sample to retrieve a valid sample value for your call.

Example

To retrieve a list of datasets from the geospatial API, call the following REST API in your REST client:

GET https://api.ibm.com/geospatial/run/na/core/v3/datasets
Headers X-IBM-Client-Id: geospatial-<paste your client ID from the developer console>
Auth Authorization: Bearer <paste your JTW that you obtained in the previous steps>

Your REST client sends the GET call, along with its required parameters and authentication, and sends back a successful 200 OK response with the contents in the body:
Datasets API call

Results

After you have authenticated with the platform and successfully tested a REST API call, you are ready to call the Environmental Intelligence REST APIs that best suit your business needs.