In today’s digital world, engineering enablement teams working on independent features and APIs experience constant pressure to devise faster ways to deliver customer outcomes.
Through this repetitive cycle of incoming user and enterprise demands followed by delivery, the modern APIs that engineering teams are working on are a direct result of the aggregation of capabilities built within the organization using external services, which ultimately get exposed to end users via a single, unified application.
As the number of components and applications increases within an enterprise– particularly in scenarios where an API no longer fits business requirements and subsequently gets copied and changed– code de-duplication becomes an extremely time-consuming process.
This leads to a high maintenance and ownership cost and introduces fragmentation in the internal ecosystem.
Today, we are introducing Platformatic Composer, a new way to develop, deploy and consume aggregated APIs, starting with OpenAPI composition across multiple HTTP/REST API sources.
Composer aggregates APIs, guaranteeing low-latency communication in cooperation with the Platformatic Runtime environment, fitting seamlessly together. Using Platformatic Composer can enable engineering teams to reap the benefits of a distributed system while having one singular entry point in order to minimize complexity.
What is OpenAPI?
OpenAPI is a format that can be used to describe/document RESTful apis. It is also known as a Swagger Specification. There are a lot of tools that can work with this format, including: Swagger UI (generates a website where you can see all routes in a suitable way), client generators (almost all languages have some library that allow to generate a client from OpenAPI definitions; @platformatic/client one of them).
All Platformatic services expose automatically-generated OpenAPI documentation.
How does it work?
Composer provides a base on which to build complex applications, simply. With our composition feature, developers can create custom APIs by combining different endpoints without writing code, all just with a simple configuration. This removes friction and repetitive tasks by providing a system requiring the APIs you need and a single interface to connect to, without removing the flexibility to customize and extend offered by Platformatic.
Combine services
Composer is built on top of Platformatic Service, and has all of Platformatic Service’s features: metrics, plugins autoload, hot reload etc.
There are two different ways to provide an OpenAPI to the composer.
1) If a composed service exposes an OpenAPI, the user can specify the OpenAPI URL in the Composer config, and Composer will automatically fetch it. By default, all Platformatic services expose OpenAPI on the “/documentation/json” URL.
{
"id": "auth-service",
"origin": "https://auth-service.com",
"openapi": {
"url": "/documentation/json"
}
}
2) Alternatively, users can specify a composed service OpenAPI schema manually. To do so, they will need to add a schema file to the project and set the path to the schema instead of the URL in the composer configuration.
{
"$schema": "https://platformatic.dev/schemas/v0.25.0/composer",
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"composer": {
"services": [
{
"id": "auth-service",
"origin": "https://auth-service.com",
"openapi": {
"url": "/documentation/json",
"prefix": "auth"
}
},
{
"id": "payment-service",
"origin": "https://payment-service.com",
"openapi": {
"url": "/documentation/json"
}
}
],
"refreshTimeout": 1000
},
"watch": true
}
Refresh timeout
Composer scans your API to detect changes via continuous integration. As such, anytime something is added into your service infrastructure, Platformatic’s composer will reflect these changes in its composed API. In a situation where one of your composed services go down, Composer will continue working, but remove the impacted service API in question from the composed API.
API collisions
It might happen that two or more of your APIs have routes with the same path.
If you encounter a conflict like this, Platformatic Composer will throw an error during startup. To avoid this, you can use API prefixes. By adding a prefix option to your API configuration, all of your routes will subsequently be prefixed with it.
Composer can be executed by Platformatic Runtime just like any other Platformatic app.
An entrypoint service is one that is exposed to the public network, while all other services remain private. If you want to expose APIs from multiple Runtime services, using Composer as an entrypoint makes sense.
Note:
If Composer is executed inside of the Runtime, you shouldn’t specify the “origin” parameter in the composer configuration. In this case, the Composer will use a service ID to connect to the service.
Composer config without origins (for Runtime):
{
"$schema": "https://platformatic.dev/schemas/v0.25.0/composer",
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"composer": {
"services": [
{
"id": "auth-service",
"openapi": {
"url": "/documentation/json",
"prefix": "auth"
}
},
{
"id": "payment-service",
"openapi": {
"url": "/documentation/json"
}
}
],
"refreshTimeout": 1000
},
"watch": true
}
Composer Configuration for Local + Remote services:
{
"$schema": "https://platformatic.dev/schemas/v0.25.0/composer",
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"composer": {
"services": [
{
"id": "auth-service",
"openapi": {
"url": "/documentation/json",
"prefix": "auth"
}
},
{
"id": "payment-service",
"openapi": {
"url": "/documentation/json"
}
},
{
"id": "metric-service",
"origin": "https://metric-service.com",
"openapi": {
"url": "/documentation/json"
}
}
],
"refreshTimeout": 1000
},
"watch": true
}
Help! My API does not expose an OpenAPI schema– what should I do?
If you wish to automatically compose your application API with Platformatic Composer, you’ll need to make sure that it exposes OpenAPI documentation on one of its routes.
If it's a Platformatic application, you’ll need to enable an "openapi" setting to generate and expose OpenAPI documentation on the /documentation/json endpoint.
If it's a Fastify application, you can use the "@fastify/swagger" plugin to generate and expose the OpenAPI documentation. In all other cases, you can either generate a documentation file and add it to the composer project or expose it from your application manually.
If it’s a remote service that does not offer an OpenAPI definition, you can craft your own (take a look at https://learn.openapis.org/ if you are just getting started) and provide Platformatic Composer with a definition file, like so:
{
"$schema": "https://platformatic.dev/schemas/v0.26.0/composer",
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"composer": {
"services": [
{
"id": "auth-service",
"openapi": {
"file": "./auth-service.json",
"prefix": "auth"
}
},
{
"id": "payment-service",
"openapi": {
"url": "/documentation/json"
}
},
{
"id": "metric-service",
"origin": "https://metric-service.com",
"openapi": {
"url": "/documentation/json"
}
}
],
"refreshTimeout": 1000
},
"watch": true
}
As we have seen, Platformatic Composer enables developers who are short on time and resources to easily and quickly create custom APIs with just a single configuration, removing friction and repetitive tasks by providing a single interface.
Are you ready to try out Platformatic Composer?
