Defining HTTP endpoints using APIs

Edit online
You can send alert notifications to an endpoint. Use the /endpointdefinitions API to define the endpoint.

Before you begin

Note: Currently, you can only define endpoints by using the API.
Get a JSON Web Token (JWT) for your POST API call to the /endpointdefinitions API. For more information, see API authentication.

Before you make the POST API call, create an API key. If your HTTP endpoint is protected by a username and password, the value of the API key must be base64 encoded as username:password. Otherwise, use any value.

Step 1: In the following example, the API key is called MyApiKey.
Example of a PUT API call to provide the API key.
To encode the username and password, from the command line of a Mac OS operating system, enter:
echo -n my_user_name:my_password | base64
You'll use the API key in the JSON payload of your POST request.

About this task

For more information about the /endpointdefinitions API, see the Endpoint Definitions API on API Hub.

The URL includes a {geo} field, which is a 2-letter code that represents the region. For North America, the code is na.

Procedure

  1. Define and register the group by making a POST API call that is similar to the following example.
    URL 
    https://api.ibm.com/infohub/run/metadata/api/v1/na/endpointdefinitions
    Method POST
    Content-Type application/json
    Body 
    {
   "endpointType": "AlertEndpoint",
   "logicalName": "{endoint_logical_name}",
   "apiKeyName": "{key}",
   "webhookPayloadUrl": "{for example, https://www.example.com}",
   "allowedOperations": [
       "create",
       "update",
       "delete"
   ],
   "isMetadataOnly": false,
   "isPublicUrl": false,
   "isGloballyVisible": false,
   "tenantId": "{tenant_ID}",
   "name": "{endpoint_name}",
   "authType": "basic",
   "contentType": "default"
}
    • The POST request produces a 201 response that contains an ID field in the response body. Note this endpoint ID so that you can use it in future to complete tasks, such as defining alerts that refer to this endpoint definition.
    • Include the following key value pairs in the header:
      
  Authorization: Bearer {{your-JWT-token}}
  x-ibm-client-id: infohub-{{your-tenant-id}}
    • Add tenantId as a field.
    • Set endpoint.Type to AlertEndpoint.
    • Set the endpoint URL in webhookPayloadUrl.
    • In allowOpertions, define the set of allowed operations as create, update, and delete.
    • When using OAuth type authentication, include customParameters in the Body.
      Body 
      
{
"endpointType": "AlertEndpoint",
"logicalName": "{endoint_logical_name}",
"apiKeyName": "{key}",
"webhookPayloadUrl": "{for example, https://www.example.com}",
"allowedOperations": [
"create",
"update",
"delete"
],
"customParameters": [
{
"name": "oauth_token_endpoint",
"value": "{oauth_token_endpoint}"
},
{
"name": "client_id",
"value": "{client_id}"
},
{
"name": "client_secret",
"value": "{client_secret}"
},
{
"name": "grant_type",
"value": "client_credentials"
},
{
"name": "scope",
"value": "{scope_value}"
},
{
"name": "set_basic_authorization_header",
"value": "true"
},
{
"name": "content_type_header",
"value": "application/x-www-form-urlencoded"
}
],
"isMetadataOnly": false,
"isPublicUrl": false,
"isGloballyVisible": false,
"tenantId": "{tenant_ID}",
"name": "{endpoint_name}",
"authType": "basic",
"contentType": "default"
}

    • Add oauth_token_endpointas a field.

    • Add scope_valueas a field.

    • Add client_idas a field.

    • Add client_secretas a field.

    • Do not pass the client_secret or client_id directly; these fields must be encrypted first. For more details, refer to the information mentioned in the above step 1.

  2. Get a list of endpoints. Make the following GET API call:
    URL 
    https://api.ibm.com/infohub/run/metadata/api/v1/na/endpointdefinitions
    Method GET

    This API supports the following optional URL parameters:

    limit
    Limits the number of endpoint definitions that are returned to the integer value of the limit parameter. If no limit parameter is specified, the default limit is 10.
    offset
    Skips the first N endpoints. The offset is zero-based. If no offset is specified, the default offset is 0.
    fields
    A value that can contain a comma-delimited list of fields to return in each returned endpoint definition. For example, if the parameter is set to &fields=name,endpointdefinitionId, then only the name and endpointdefinitionId fields for each endpoint definition are returned. If no fields parameter is passed, then all fields are included for all returned endpoints.
    name
    Filters the endpoint definitions that are returned to only those endpoint definitions with a name that matches the value of the name URL parameter. The name URL parameter accepts wild cards and matches rules. If no matching rules are found, an empty array is returned. If no name filter parameter is specified, the default behavior is to return all endpoint definitions, up to the page size that is specified by the limit parameter.
  3. To delete an endpoint, use the DELETE method.

    Add the endpoint ID from the preceding response to the URL. For example, "endpointId: "23dd6370-ae05-490d-9ef4-57b798b62f0f".

    URL 
    https://api.ibm.com/infohub/run/metadata/api/v1/na/endpointdefinitions/23dd6370-ae05-490d-9ef4-57b798b62f0f
    		 Change the method to DELETE and add the endpointid at the end of the URL. You do not need a body for this request.
  4. To edit the endpoint, use the following API: 
    URL: https://api.ibm.com/infohub/run/metadata/api/v1/na/endpointdefinitions/{alertEndpointId}
Method: PUT
Content-Type: application/json
Body:
{
    "logicalName": "{endoint_logical_name}",
     "apiKeyName": "{key}",
     "webhookPayloadUrl": "{for example, https://www.example.com}",
     "allowedOperations": [
         "create",
         "update",
         "delete"
     ],
     "tenantId": "{tenant_ID}",
     "name": "{endpoint_name}",
     "authType": "basic",
     "contentType": "default",
     "isPublicUrl": false,
     "isGloballyVisible": false
 }