Talend API Designer Best Practices

TalendSolutionExpert · Jan 22, 2024 9:35:30 PM

This article describes a set of best practices for Talend API Designer, using a real-world example. These best practices are applicable for the following products and versions running on a cloud environment:

Talend API Designer
Talend Studio R2020-08-7.3.1

For information on the functionalities of Talend API Designer, see the Talend Cloud API Designer User Guide available in the Talend Help Center.

To better understand these best practices, consider an example use case for designing an API, named Yousubscribe, based on customers and subscriptions.

A simplified data model for this API is shown in the table.

Customer	Subscription_type	Subscription
id (PK) email firstname lastname	id (PK) type price	id (PK) customer_id (FK) stype_id (FK) start_date end_date

Examples of API operations you could design to work with the data model include:

Get user (filter), get user list (filter), create, update (id), delete customer (id)
List subscription_types, get (type), create, update
Create subscription (email, type), delete subscription (id), list subscriptions by users (email)

This document provides examples of how to implement these operations in alignment with best practices.

API naming best practices

It is important to adopt standard naming conventions for the different artifacts (APIs, resources, and methods) in your API. Some key guidance for naming conventions is shown in the table.

API

Use an explicit name for your API. For example, use the name of the main application.

API Resource

The resource is a business element and must have the name of the business element. A resource is a collection of data, so the name should be plural. The resource name is part of the URI; use lowercase with an underscore (_) separator to avoid any confusion with cases and special characters in browsers, in Talend API Tester, and in the code (Talend Studio).

Path Variable (when used as a subResource)

When using a path variable to get access to a unique element (such as the customer ID of a customer), use the following syntax: /customers/{customer_id}

When using a path variable to access data across a relation between two resources (for example, the subscriptions that belong to a customer), use the following syntax: /customers/{customer_id}/subscriptions

Do not use special characters and avoid hyphens (-); use underscores (_) instead. The hyphen (-) character can’t be parsed in a Java variable and requires more coding to refer to it in Talend Studio.

Example of extra coding if you are using a hyphen:

You have a header, "Avec-Tiret", in your request, and you want to get it and put it in a field, set as “avec_tiret” in your structure.

Add a tJavaRow component after the tRESTRequest component with the following code:

// Get the request and headers
java.util.Map<String, Object> restReq = ((java.util.Map<String, Object>)globalMap.get("restRequest"));
javax.ws.rs.core.MultivaluedMap<String, String> h = ((javax.ws.rs.core.MultivaluedMap<String, String>) restReq.get("ALL_HEADER_PARAMS"));

// Get the header "Avec-Tiret" in the field "avec_tiret" of my structure
output_row.avec_tiret = h.getFirst("Avec-Tiret")

Data Types

Use camel case or underscore (_) separators in structure names, such as subscription_list.

Use JSON format as much as possible because it is the standard for REST APIs. Some applications also use application/xml. It can be added at this level too, and the responses body media types then depend on the Accept header of the requests.

Avoid complexity in the structure. Simply structures are easier to process (from the server and client side)!

With Talend API Designer, it is easier to create the structure from an example using the Generate from JSON example link. This way, the structure is created automatically, and you already have an example for the mock.

Using components to reduce duplication

Components are an OAS 3.0 feature. You can use them only if you are developing the REST API as a Data Service in Talend Studio, not with web services in Routes because OAS 3.0 is not yet supported. You can only use components if your external API tools, such as your API gateway, are compatible with OAS 3.0.

Components are common elements that can be used anywhere needed in the contract. Use them as much as possible to reduce duplication and maintenance overhead. In this example, a component called Generic Message is created to define a generic no content response. This response, with a 204 HTTP code and a specific message body, displays whenever a request query retrieves no data.

Using HTTP verbs for operations

Be sure to use HTTP verbs for operations on the resource based on cross-industry standards, such as POST for create, and PUT or PATCH for update. Examples in the context of the YouSubscribe API are shown in the table.

HTTP Verb	CRUD	Description
POST	Create	Create a customer, subscribe a customer
GET	Read	Get customer’s subscriptions, get subscription types, get subscriptions
PUT	Update/replace	Update customer information
PATCH	Update/modify	Update subscription price, update subscription end date
DELETE	Delete	Delete subscription
HEAD	Read	Same as GET but without the body in the response (headers only)
OPTIONS	-	Get communication options from the target resource

Do not use special characters, for example, an apostrophe (‘), in the operation description (label).

Using HTTP responses effectively

Always use standard HTTP response codes to ensure interoperability with connected systems, such as API clients.

For the YouSubscribe API, the following response codes are defined to be used globally, that is, for all resources and operations:

Parameters validation: 400 (Bad request), 406 (Not acceptable)
Security (if required): 401 (Unauthorized), 403 (Forbidden)

Similarly, define and implement the following response codes for each operation:

Operation	Entire Collection (for example, /customers)	Specific Item (for example,/customers/{id})	Comment
GET	200 (OK)	200 (OK), single customer 404 (Not Found), if ID not found or invalid 204 (No Content), for no result 206 (Partial Content), if the request is too large to send the entire result, pagination must be used or use 303 (See Other) to give the pagination request	Use pagination, sorting, and filtering to navigate big lists
POST	NA (unless operation for entire collection)	201 (Created) 409 (Conflict) if resource already exists	Location header with a link to /customers/{id} containing new ID
PUT	NA (unless operation for entire collection)	200 (OK) 404 (Not Found), if ID not found or invalid
PATCH	NA (unless operation for entire collection)	200 (OK) 404 (Not Found), if ID not found or invalid
DELETE	NA (unless operation for entire collection)	200 (OK) 404 (Not Found), if ID not found or invalid

Catching internal server errors (response code 500)

Internal server errors, represented by the 5XX series of response codes, must always be intercepted, and an appropriate response should be sent to the client. Because 500 response codes usually cannot be handled by clients, it is important to make them more meaningful so they can be understood and processed automatically, for example, by identifying that the error is due to a timeout or a malformed parameter.

Internal server errors can also leak internal information about the API that you may not want visible to clients.

Organizing your items in Talend API Designer

By default, Talend API Designer sorts and organizes your objects by types, and specific icons make them more identifiable. You can also drag and drop to move your elements.

When dealing with multiple resources, it is a good idea to add “sections” to capture common items, similar to how you use folders with files:

A section with the <resource name> to store everything related to the resource
A section named Structures to store all your data types
A section named Operations to store all your resources and operations

You can see this arrangement for the YouSubscribe API:

Protecting against SQL injection

SQL injection is a common security breach involving APIs. Always decorrelate the attributes of the responses from the attributes of your data store. Do not directly expose the names of your database fields (attributes if you are using NoSQL) directly in your API responses.

Using query parameters appropriately

Use query parameters for the following scenarios:

Filters: for example, to return only “gold level” subscriptions, use /subscriptions?type=gold
Pagination: for example, for a total of 250 elements:
- /subscriptions?page=1&limit=100 -> Get the range 1-100
- /subscriptions?page=2&limit=100 -> Get the range 101-200
- /subscriptions?page=3&limit=100 -> Get the range 201-250
Sorting: for example, to sort subscriptions in descending order, use /subscriptions?sort=desc

Do not use special characters in query parameter names, and use underscores (_) instead of hyphens (-). The hyphen (-) character cannot be parsed as a Java variable and requires specific code in Talend Studio as a workaround.

Using pagination correctly

Use pagination when the response has a lot of elements. There are multiple ways to handle pagination; the best way depends on client needs.

A common practice is to use limit and offset (or page) query parameters in the request. For example, to return the second page of 100 subscriptions, use /subscriptions?offset=100&limit=100.

When you use pagination, also make use of HTTP response codes that highlight issues or the status of the request, including:

206 (Partial Content) is used if the limit query parameter is not found or is too high and the default max limit is reached.
303 (See Other) is used with the Location header, including the request with the limit and offset parameter.

In the response header, set the next value (next offset or next page) and the navigation links (previous URL, next URL) to loop until the end of the list.

You can also use the HTTP response headers to store additional information about the pagination state, for example, Content-Range: offset-limit/count.

However it is implemented, pagination implies multiple calls, so the queries must always return the same result. Having the same (and absolute) sort key is mandatory.

Versioning

Talend recommends including the version in the API path, for example, /yousubscribe/v1/. The relative path, v1, is defined in Talend Studio according to the API definition version (for example, 1.0.0).

Note: Use /something/v1/ in the URI, not simply /v1/<resource>. Otherwise, you will have endpoint conflicts if you deploy several APIs in a Runtime.

To avoid managing too many versions, change the API version only when there is an impact for the client. You will expose a new endpoint with the v2 URL, and both v1 and v2 will be available. For example, you may want to create a new version when there is a new relative endpoint, new mandatory parameter, or new outputs. However, you might not want a new version for optimizations, optional parameters, operations, or new resources.

Note: As much as possible, try to have backward compatibility to keep the current version.

Creating a new version

Create the new version from a previous version.
Configure the new version, then click Create.
In Talend Studio, duplicate the Yousubscribe_v1 Job or Route in Yousubscribe_v2, and change the tRestRequest or cRest endpoint accordingly. Update the REST API contract to Yousubscribe 2.0.0 in Talend API Designer.

Generating documentation easily

Talend API Designer generates documentation automatically, based on all elements of the design.

To improve the documentation quality, fill in the descriptions and examples.

Add text elements to include additional information, such as an About section.

Summary

This article introduced some best practices for using Talend API Designer to implement APIs.

Talend API Designer Best Practices