How to Create an API and a Path for API Requests
  • 08 Mar 2024
  • 6 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

How to Create an API and a Path for API Requests

  • Dark
    Light
  • PDF

Article Summary

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

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:

new project.png

Creating a new Project when you already have Projects

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.

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

corezoid create-project light.png

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

project create name enter.png

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

ctrated project refresh.gif

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.

Adding Stages manually

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+:

crete alias.png

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:

create path 1.gif

  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:

create path menu.png

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

Method for the Synchronous operation

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:

calback url

  • 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
Construction used in API Call node URL

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+ :

crete key.png

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:

sharing the process.png

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.

x-status code

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:

copy base URL.png

As a testing option using Postman, do the following:

Send an API request using the basic authorization

instr6.png

Username is the API key login

Password is the API key secret key:

instr7.png

Check whether the task was sent

postman screen.png


Was this article helpful?