How to create API endpoints without coding

[dgudkov]

EasyMorph Server allows quickly creating custom web APIs without coding, with just visual drag-n-drop workflows. This dramatically simplifies and speeds up designing custom APIs. Traditionally, designing a web API used to be a complex software development project that required a team of developers, testers, a project manager, etc. With EasyMorph Server, designing and deploying a custom web API is so much simpler and faster that it becomes a configuration task, instead of a software development project.

Here is a step-by-step guide on how to create and configure custom API endpoints with EasyMorph Server. The guide assumes that you have downloaded and installed EasyMorph Server and EasyMorph Desktop and have a basic idea of how to create visual workflows in EasyMorph.

What a web API can be used for?

Web APIs use the massively popular HTTP protocol and therefore can be used in many ways, usually to enable real-time machine-to-machine integration. Just a few examples:

• Accepting data submitted in forms on web-sites
• Retrieving information by a request from another application (e.g., return a price for a given product SKU)
• Saving information received from another application (e.g., receiving financial transaction data from another application and saving it in a database)
• Reacting to an event in another application (e.g., a new order was created therefore an email is sent)

How does a web API work?

A web API works using web requests (a.k.a. HTTP requests). In a nutshell, the principle is simple:

1. An application sends a web (HTTP) request to EasyMorph Server. The request can have parameters and a payload (data).
2. Based on the request parameters and payload (whichever is present) EasyMorph Server uses a visual EasyMorph workflow to calculate a web (HTTP) response that is immediately sent back to the application.

For example, a request can mean "Give me the technical specifications for the product whose SKU is 12345". In this case, the request contains the product SKU, and the response contains a data structure (e.g., JSON or XML) with the technical details for the product.

Web requests, in a nutshell, are also described in this article: Making your data better with web APIs.

It should be noted that:

• Server responds in real-time, i.e., the application waits for the response and expects to obtain it as soon as possible (most frequently, web requests are responded to within seconds, sometimes faster than 1 second).
• Requests are independent of each other. The Server can process many similar requests in parallel, sending an individual response to each request.
• While in theory, all requests of any type can be sent to a single Server web address (URL), in reality, a web API has different URLs (also known as endpoints) to serve different types of requests. For instance, one URL for customer data, one URL for product data, and so on.

Configuring API on EasyMorph Server

To enable custom API in a Server space, log into the Server as administrator, go to Space settings and turn them on.

Note that in the Team edition of EasyMorph Server allows custom API endpoints in only one space, while in the Enterprise edition, any space can have a custom API.

When enabled, you should see a new tab "API endpoints".

Creating an API endpoint

Press the "Create endpoint" button and enter the new endpoint's name and URL.

The endpoint name is any human-friendly name for display in EasyMorph. This name is only used to distinguish endpoints in EasyMorph from each other more easily. This name is not exposed to external applications and is not used anywhere outside of EasyMorph.

The endpoint URL forms the public URL (web address) of this endpoint that should be used by external applications for sending web requests. The final URL is concatenated from 3 parts:

• The Server web address (machine name + port as configured by your Server administrator) followed by /web-api. For example, https://em-server.local:6330/web-api
• The base URL path of the Server space. For instance /default. The base URL path can be seen in the 2nd (from the top) screenshot above. To change it, press the "Configure" button (it can be seen in the same screenshot).
• The endpoint URL path that was configured when the endpoint was created or in the endpoint settings. For example, test/{ID}

Using the examples above, the full endpoint URL (for sending requests) would be:

https://em-server.local:6330/web-api/default/test/{ID}

Note: the web-api part can't be changed. Everything else can.

At this point, you might be wondering what the {ID} part of the endpoint URL is. This part is optional and is included for educational purposes. The endpoint URL can have multiple segments, for instance, test/abc/xyz. Any of these segments (except for the 1st one) can be replaced with a parameter name in curly braces. When the endpoint's EasyMorph workflow is executed, the workflow must have a parameter with the same name, and it will be assigned with the value of the respective segment path. (How to configure workflows for endpoints will be explained later in this article.)

For instance, let's assume the full endpoint URL is

https://em-server.local:6330/web-api/default/test/{ID}

Now, another application sends a web request to

https://em-server.local:6330/web-api/default/test/12345

In this case, the endpoint's workflow parameter ID will be assigned with 12345. If the endpoint doesn't have a workflow, or the workflow doesn't have a parameter named ID, the request will fail.

When the endpoint is created, you see the endpoint settings page.

Immediately after creation, the endpoint can already receive web requests. For instance, you can send a test request to this endpoint from Postman or from EasyMorph using the "Web request" action. However, at this point, the endpoint is not ready yet to process requests and produce responses, because it needs an EasyMorph project (workflow) to do that.

The 10 most recent incoming requests are stored as samples. There are two collections of request samples - successful requests, and failed requests. You can see requests in these collections in the tabs "Successful requests" and "Failed requests" in the screenshot above.

For instance, if you send a web request to the endpoint we just configured, it will appear in the "Failed requests" because the endpoint doesn't have an EasyMorph project yet and therefore the request will be received but will fail.

Creating an EasyMorph workflow

Now, let's create an EasyMorph project that will handle web requests sent to the endpoint and produce responses.

Before we start doing this, it might be a good idea to send one or more test requests to the endpoint so that we have them in the sample collection of failed requests.

Launch EasyMorph Desktop and create a new project. Make sure the Server Link is configured and points to the same space where the endpoint is created. It's required to retrieve sample requests.

If the endpoint URL has parameters (in our case it's one parameter named "ID"}, create workflow parameters with the same names. So in our case, the workflow should have one parameter "ID".

Add action "Incoming HTTP request" and press the "Populate" button.

In the dialog, pick a sample request, press "Next" and "Apply".

The action produces a 1-row table with all metadata (URL parameters, request headers) and the request body (in column "Request-Body"). Now you can use EasyMorph actions and functions to calculate data that needs to be returned (if any).

The "Incoming HTTP request" is optional. If all you need from a request is a few values passed via parameters, you can assign workflow parameters manually with the necessary values.

Regardless of whether the response should contain some data or not, you can use the "Construct HTTP response" action to construct a response. Put the action as the last step of the last table of the workflow. Mark the table as the default result table of the workflow.

The "Construct HTTP table" produces a 1-row table that contains all the necessary metadata of the response and the response body (column "Response-Body"). For successful responses, pick response code 200 (OK) and specify the column with the response body (if needed). EasyMorph Server will use the 1-row table produced by the workflow to construct a web response. It expects columns with the names "Response-HttpCode" (mandatory) and "Response-Body" (optional). The rest of the columns will be constructed as response headers with respective names.

Save the project, and publish it to EasyMorph Server.

Finishing endpoint configuration

At this point, we have an endpoint that receives web requests, and a project (published on EasyMorph Server) that calculates a response. All we need to do is to put them together.

In the endpoint, settings select the project and assign project modules to HTTP methods. One project can have multiple modules, and each module can serve a particular HTTP method (verb) such as GET or POST

Note that if the endpoint URL has a parameter (such as "ID" in our example), then all modules should have a parameter with the same name.

The endpoint is now ready to use.

What you have learned from this article

• How to configure a Server space to enable API endpoints
• How to create an API endpoint
• How the full endpoint URL is concatenated from the Server URL, base URL, and the endpoint URL path
• What are the collections of sample requests
• What the "Incoming HTTP request" action is for
• How to retrieve sample requests in EasyMorph Desktop
• What the "Construct HTTP response" action is for
• How to construct a successful HTTP response
• How to tie a visual EasyMorph workflow to an API endpoint
• How to configure an API endpoint to use a specific module of a workflow to serve a specific HTTP method (such as GET)
• How to assign a module parameter from an URL path segment

What's remaining outside of this article

The custom API functionality in EasyMorph is suitable for many advanced cases and scenarios not covered in this article. Quick remarks on some of the advanced features:

API authentication modes:

• None
• API key
• Basic HTTP
• Windows Identity (requires Active Directory and thus the Enterprise edition of EasyMorph Server)

Besides URL path segments, workflow parameters can also be assigned with:

• URL (query) parameters
• Request headers
• Request body
• Full request URL
• HTTP method
• IP address
• Request identity (when authentication is enforced)
• Custom values

Support for version control systems (such as git). Endpoint configurations are stored in XML files in the .endpoints directory and can be checked in git together with the respective EasyMorph projects.

Zero-downtime updates. The base folder of an API configuration can be switched to another folder with another (updated) API configuration. The switch happens instantly which allows updating API endpoints on the fly with no downtime. To create a new configuration, clone the current folder with the endpoints and projects and modify it in a separate environment (space). Then switch the base folder to the new configuration when it's ready.

API versioning. Use two or more spaces to have two or more versions of API working simultaneously.

Support for DEV/TEST/PROD environments. Use different spaces and even different Servers to separate DEV, TEST, and PROD environments. In PROD environments, you can disable editing endpoints and remove technical details from error responses.

In the initial release, CORS enables all sources. In future releases, we will add the ability to configure CORS settings in a more granular fashion.

A workflow can construct both successful and error HTTP responses (just remember to have a single result table). Also, a workflow can construct a response that initiates a file download or HTTP redirect.

[RJO]

Hi,

This feature is awesome and you explain it very well. How does it work when you talk about “Windows identity” during authentication ?

Do you mean that if I use the desktop which is already connected to a server workspace, I will be automatically authenticated so I don’t need to authenticate when using the API ? But in the case where for example I call the API from Excel, not from easymorph desktop anymore, I’m quite sure this is not working right ? How would the request pass my Windows Identity in this case ? It would not work according to me. If you can provide examples where Windows Identity works and how it works ?

[dgudkov]

For Windows Identity authentication to work there are 2 conditions:

1. The authentication mode in the API settings should be set to “Windows Identity”. In this mode, for every request that client sends, the Server responds with a challenge (in this case, for NTLM authentication) – a special combination of headers that require the client to provide a Windows Identity.
2. The client that sends the web request should “know” how to respond to such challenges. It can send back to the Server a Windows Identity, or show a pop-up to the user to obtain the identity from the user.

Therefore, it depends on the client, whether it supports NTLM authentication with passing a Windows Identity, or it doesn’t. For instance, all web browsers in Windows handle NTLM authentication automatically. EasyMorph Desktop also can do that. But can Excel handle it? I don’t know. Maybe yes, maybe no.

If a client doesn’t support NTLM authentication and it’s required by API configuration, then the API Server won’t even start the workflow and return 401 (Unauthorized) to any request to any endpoint.

[RJO]

Is there a limitation to the size of the reponse ? I mean at least everything must be contained in one cell in Easymorph (response-body) and I don’t know if there’s a size limit of information that one single cell can contain in easymorph ?

[dgudkov]

One cell in EasyMorph can contain up to 2GB of text in the UTF-8 encoding. I suppose that’s more than any practical response body size.

For very large datasets that need to be delivered as HTTP responses, it might be a good idea to return a response that initiates a download. The “Construct HTTP response” action has the “Download file” mode for that purpose.

[cgr-stez]

Hi, Thanks for your explanation of this feature, but i need some more explanation.

Here you say:
The “Construct HTTP table” produces a 1-row table that contains all the necessary metadata of the response and the response body (column “Response-Body”). For successful responses, pick response code 200 (OK) and specify the column with the response body (if needed). EasyMorph Server will use the 1-row table produced by the workflow to construct a web response. It expects columns with the names “Response-HttpCode” (mandatory) and “Response-Body” (optional). The rest of the columns will be constructed as response headers with respective names.

Can you explain how to achieve response based on job result?
For example:
In my job i run a external cmd command and then I want to return a 500 response if command return some errors otherwise i want to return 200 response if command return successful result.

Can i set default result table on success flow table ?

Thanks

[dgudkov]

The solution is to use the “Either table” action. The action is simple - it returns the output of one table if it’s not empty, otherwise, it’s the output of another table.

So in your workflow should be one result table, and in that result table use the “Either table” action that merges HTTP responses from other tables, of which only one should be calculated.

Schematically:

<empty> EITHER success => success
error EITHER <empty> => error

Alternatively, you can use the “Append table” instead of “Either table” (appending an empty table doesn’t change the current table), but using “Either” is more idiomatic.

[cgr-stez]

Thank you @dgudkov for your reply, i’ve already tried to use “Append table”, and now i also tried to use “Either table” but for this scenario the http response returned is :

{
    "error": {
        "code": "EXCEPTION",
        "message": "Response-HttpCode is missing or has a wrong value"
    }
}

here is my flow:

[dgudkov]

Hmm… the workflow looks right and the “Response-HttpCode” column exists and contains the correct value in your screenshot.

Can you add the “Export dataset” or “Export to delimited text” action after the last “Either table”? This will save the exact result of the table. See if the “Response-HttpCode” column exists and contains the correct value.

Also, in your workflow, you can add the “Incoming HTTP request” action. It contains the “Populate” button that allows retrieving request properties and assign workflow parameters exactly as they were for the failed request. It could be that neither of your workflow branches produces an HTTP response and the result table is empty or contains the wrong columns.

[cgr-stez]

I’ve already done this steps to grab the requests… I’ve previously follow your tutorial in this post, but it seems when i add some actions after “Construct HTTP response” the response returned is not correct. Following your suggestion to export the dataset at the end of the flow now i can see the data received when project receive an http request, and here is an export::

but if i pick a request from list

and execute flow… it works!!
At the setted result table i can see the same columns and data i’ve posted in the previous post

[dgudkov]

Something isn't right here. The dataset in your screenshot contains the request, while I expected it to show the response (that leads to failure) and whether it contains the "Response-HttpCode" column and the code itself.

@cgr-stez

but it seems when i add some actions after “Construct HTTP response” the response returned is not correct.

To construct a "real" HTTP response, the Server expects the workflow to return a table in a specific format. For instance, it must have the "Response-HttpCode" column. The "Construct HTTP response" action constructs the columns necessary for the Server to construct an HTTP response.

However, if you add actions that modify (or delete) the columns created by the "Construct HTTP response" action, the result table might get incorrect columns, and the Server won't be able to construct a "real" HTTP response from them.

[cgr-stez]

Ok, i understand that! But i don’t understand why if i take failure request from list and click on “Reload and run” project works well and the output table is correctly formatted!
I don’t add any other actions after “Construct http response” outside of “Derive table” and “Either table”.
Testing flow exporting tables in different steps i saw that after “incoming HTTP Request” of my post request the export have a Request-Body empty

[ckononenko]

@cgr-stez

Testing flow exporting tables in different steps i saw that after “incoming HTTP Request” of my post request the export have a Request-Body empty

Request-Body is empty due to it being bound as a Module Parameter. This can be configured in the API endpoint settings.

[ckononenko]

Since version 5.4.2, we have changed how the HTTP request data is bound to the “Incoming HTTP request.”

The “Incoming HTTP request” action now returns columns with the request body, parameters, headers, and other metadata, even if they were assigned to module parameters in the API endpoint settings.

Also, multiple query parameters with the same name (like ?par=q1&par=q2) will produce a single column (par) in the “Incoming HTTP request” with comma-separated values (like q1,q2).

[Luis_Hernandez]

How to create API endpoint for post method with workflow

i received this error

{“error”:{“code”:“CONFIGURATION_ERROR”,“message”:“Method Not Allowed”}}

[ckononenko]

Hi @Luis_Hernandez
Have you bound the HTTP POST method to the project Module in the endpoint settings?

[Luis_Hernandez]

Hi

Yes i put the post method in the endpoint settings

[ckononenko]

Hi.
It seems that you send a request with an HTTP method other than HTTP POST or to the wrong endpoint.

Which tool/utility do you use to send the HTTP request?
Ensure you have configured your client to send a POST request to the correct endpoint URL.
Also, check the Failed Requests tab. This tab should contain a recent failed request for the current endpoint and can be used for debugging purposes, including validating the request HTTP method.

In case of Failed Requests don’t contain any data, check other endpoints that recently failed. Request samples must be set to "Successful and failed " in the API Server settings.