API service for http request

🟡 Intermediate

script

This tutorial will guide you through creating a script that use the API service to get data from an external API.

Define an API service in api-service.ospp with the target hostname and allowed modules.
Declare an endpoint in api-endpoint.ospp with path, HTTP method and default query parameters.
Write a detached JavaScript script that calls the endpoint with default and overridden parameters.
Observe the full request URL and response body in the module logs.

git checkout origin/osp-scripts-configuration .
git checkout origin/example-script-api-service-usage .

Prerequisites

A website that responds to HTTP requests. We will use Httpbin.

Steps

1. Create an api service

root/api/api-service.ospp

{
    "moduleId": [
        "modules.scripts.scripts-1"
    ],
    "host": "https://httpbin.org"
}

This file define how to access the api, in this case with the hostname https://httpbin.org, and which module can use it.

It is possible add credential if required.

2. Create an endpoint

root/api/get/api-endpoint.ospp

{
    "service": "root.api",
    "endpoint": "/get",
    "method": "GET",
    "parameters": [
        {
            "type": "QUERY",
            "name": "test",
            "defaultValue": "value"
        }
    ]
}

An endpoint reference the service to use with service.

It define the path /get and the method to communicate.

In this case, the /get path allow any parameter on the query. So we define the parameter test with a default value of value.

3. Create a script to request the api every minutes.

root/script/app.js

function main() {
  let result = http.doRequest("root.api.get", {});

  if (!result.isSuccess()) {
    return false;
  }

  log.info("Default response body is {}", result.getBody());

  if (JSON.parse(result.getBody())?.args?.test !== "value") {
    return false;
  }

  result = http.doRequest("root.api.get", { test: "toto" });

  if (!result.isSuccess()) {
    return false;
  }

  log.info("Override response body is {}", result.getBody());

  if (JSON.parse(result.getBody())?.args?.test !== "toto") {
    return false;
  }

  return true;
}

main();

root/script/owner.scripts

{
    "moduleId": "modules.scripts.scripts-1",
    "sourceFile": "root/script/app.js",
    "scheduledExecutions": ["0 * * ? * * *"]
}

The script will do two request, one with the default parameter and one with toto.

The body of the response will be printed on the log.

4. Observe the response

On the response for the first request, we see that the request was sent with the URL https://httpbin.org/get?test=value, which matches the default parameter.

{
    "args": {
        "test": "value"
    },
    "headers": {
        "Accept-Encoding": "gzip, x-gzip, deflate",
        "Host": "httpbin.org",
        "User-Agent": "Apache-HttpClient/5.4.1 (Java/23.0.1)",
        "X-Amzn-Trace-Id": "Root=1-67ae0170-4d0ef9ef6821c04f1ee55b44"
    },
    "url": "https://httpbin.org/get?test=value"
}

The second request uses the URL https://httpbin.org/get?test=toto that matches the override parameter.

{
    "args": {
        "test": "toto"
    },
    "headers": {
        "Accept-Encoding": "gzip, x-gzip, deflate",
        "Host": "httpbin.org",
        "User-Agent": "Apache-HttpClient/5.4.1 (Java/23.0.1)",
        "X-Amzn-Trace-Id": "Root=1-67ae0171-3910d3e8739295f1074b2250"
    },
    "url": "https://httpbin.org/get?test=toto"
}