How to Create an API and a Path for API Requests

To use API Gateway for communicating with your process and sending requests, follow these steps:

• Create a Corezoid Project from the API Gateway menu.
• Create a process in the Project Stage to send tasks to
• Create a path within the Project.
• Configure the path, which involves creating alias (see Select Alias) and API key, and sharing your process with it (see API Key).
• Add the configured path to your Stage.
• Copy the base URL.

Creating a Project

To create a Project (which provides two APIs by default) to which you can add paths for API requests, do the following:

1. Open Simulator workspace menu and go to Corezoid section:
2. Click New project to create a new project in Corezoid:

4. In the Corezoid Projects menu that opens, click Create and select Project in the menu:

5. In the Create project menu, enter the name for your Project and click OK to create the Project:

6. Go back to Projects list in Simulator->Corezoid and click Refresh to see the newly created project in the list:

You've created a new project with two default stages, to each of which you can add path entities or simply paths. By default, each Project in the Corezoid->All APIs->Projects list provides two Stages (APIs) to which you can add paths.

Creating a Process in a Stage

After creating a Project with Stages, you need to create and configure a process you want to send tasks to using API Gateway:

• Open Corezoid Workspace tab
• Navigate to the Stage you want to add a path to in Simulator
• Click Create and select Process
• Enter the new process name and click Create
• Configure your process and click Deploy

Creating an Alias for your Process

After you've created a process to use with API Gateway, it's convenient to create and link an alias to your process. You can do this when configuring a path to the Stage before proceeding with other path parameters. To create an alias, open the Create path window and click the Select alias field and select Create alias+:

On the Corezoid Aliases page that opens, create an alias using the Create button and link it to the process you want to use with API Gateway. After that, click the refresh icon to the right and select the created alias.

After that, you can proceed with configuring other path parameters.

Creating a Path for a Stage

To create, configure and add a path to a Stage, follow these steps:

1. Click the Project you want to add a path to in the Projects list
2. Click the Stage you want to add a path to
3. In the menu that opens click Create path
4. Configure your path.

Configuring a Path

In the Create path menu, you can configure and add paths to Projects. This will include creating an alias and linking it to your process (see Select alias), and creating an API key and sharing your process with it (see API key). To do this, configure the following settings:

Path - enter the path that starts with the "/"
Method - select the method for sending requests (POST, GET, PUT, PATCH, DELETE)

• Description (optional) - you can add a text description for the resource
• Select alias - select a created alias to link it to the Corezoid process which you want to use with API Gateway.

To upload the data processed in Corezoid back to API Gateway in the Synchronous mode, you need to have an API Call node in the specified process. API Gateway provides a callback URL via the __callback_url field of request data, and you just need to specify the URL in an API Call node's settings:

• State - select active or paused process states. The Paused state means the current endpoint is unavailable and can be turned off.
• Response mode - select Synchronous or Asynchronous (task is sent without waiting for a response) modes

• Availability - choose between public and private availability of your Stage. For the public option, authorization is not required (select an API user, which will automatically be used when sending requests to Corezoid). However, authorization is needed for the private option (the user API is sent in headers).

• API Key - create an API key and grant it the Task management right to your process. To do this, click the API key field and select Create key+ :

On the Corezoid API keys page that opens, create an alias using the Create button. After that, share your process with the API key and grant the key the Task management rights:

In the Create path menu, click the refresh icon to the right of the API key field, and select the created API key in the list.

• proxy headers - adds the headers subparameter to the request parameter in the response. Turning this option on enforces sending all headers.
• proxy raw body - adds the raw_body (body raw object from request) subparameter to the request parameter in the response. By default, API Gateway transfers the body as an object. When selected, an input body is sent as a string. Depending on the Content-Type selected, API Gateway allows the transfer of body data in XML and other formats.

Proxy raw body

In addition to a standard JSON format, you can use any format for inputting data in the API Gateway. If you need to send data to the specified process in a format other than JSON, check the Proxy raw body box and the data will be sent as a string.
However, with XML in your request body, you have a conversion option. API Gateway can convert XML data to JSON before sending it to Corezoid in a task. To send XML-format data in your request to Corezoid as JSON, just do the following:

1. Select either Application/Xml or Text/Xml content type in the API Call node's settings;
2. Disable the Proxy raw body option in the API Gateway path settings.

With the Proxy raw body unchecked, the XML request:

curl -X POST -H "Content-Type: text/xml" -d '<hello>world</hello>' https://foo.api.the-company.com/bar/baz

will be forwarded to Corezoid with the following body converted to JSON:

{"hello": "world"}

API Call parameters

In the API Call node of your process, you can also add the following parameters:

• Request parameters - are returned in API Gateway request;
• Custom http code to the response headers - if you use the X-Status-Code key in the Other->Header parameters, you can send any HTTP status code between 200 and 599 that you've specified in the "value" field (similar to Sync API).
  If you use the CZ-AG-Status-Code, a Content-Type=text/html (ready-to-use HTML header) will be added to the data sent to the client.

Adding a Path

After you've configured your path, click Create to create a path. The created path will be added to the selected Stage and will be displayed in the Projects->Paths list.

Copying the base URL

After you've configured and added a path to your API, you need to test request sending via this path. To test your path, you can copy the base URL. In the Corezoid section, select your added path in the Paths list and click Copy URL:

As a testing option using Postman, do the following:

Send an API request using the basic authorization

Username is the API key login

Password is the API key secret key:

Check whether the task was sent