- Print
- DarkLight
- PDF
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:
- Open Simulator workspace menu and go to Corezoid section:
- Click New project to create a new project in Corezoid:
To create a new Project when you already have Projects in the Corezoid section, on the Corezoid->Projects page, click To all APIs and then click Create in the upper right corner.
- In the Corezoid Projects menu that opens, click Create and select Project in the menu:
- In the Create project menu, enter the name for your Project and click OK to create the Project:
- 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.
To add more Stages to your project (or remove from the Project), open the Projects menu in Corezoid, navigate to the needed Project and create a Stage or remove a Stage manually.
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:
- Click the Project you want to add a path to in the Projects list
- Click the Stage you want to add a path to
- In the menu that opens click Create path
- 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)
With the Async option disabled, it is mandatory for the process you want to use with API Gateway to contain an API Call node. You must select POST in the API Gateway Method parameter, and select POST in the Request method parameter of the API Call node.
- 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
With the Async option disabled, you need to use the following construction in the URL field of the API Call node: {{_callback_url}}
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 therequest
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 therequest
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 theContent-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:
- Select either
Application/Xml
orText/Xml
content type in the API Call node's settings; - 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 theCZ-AG-Status-Code,
aContent-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: