API changes

Enduro uses the Goa framework to build the API. Goa provides a design language which is our source of truth from which both behavior and docs are derived.

Goa generates all the code that relates to the communication transport as well as the API specification using OpenAPI. Enduro provides the implementation of the services where we include the business logic. This idea is described by Robert C. Martin in The Clean Architecture.

See also:

• Dynamic documentation in our website
• OpenAPI document (openapi.json)

API design

Our API definition can be found in the api/design package. The following example shows how we’ve described the DELETE /collection API.

Method("delete", func() {
    Description("Delete collection by ID")
    Payload(func() {
        Attribute("id", UInt, "Identifier of collection to delete")
        Required("id")
    })
    Error("not_found", NotFound, "Collection not found")
    HTTP(func() {
        DELETE("/{id}")
        Response(StatusNoContent)
        Response("not_found", StatusNotFound)
    })
})

With this design language we describe our API services, methods and types. It is also possible to implement some advanced features such different authentication methods or streaming of contents.

Backend development

After making new changes to the API design, the developer should run: make gen-goa which generates all the code under internal/api/gen, including the OpenAPI description of the API for the HTTP transport: openapi.json.

In the example above, we added a Delete method to the Collection service. The corresponding Go interface gets a new method:

Delete(context.Context, *DeletePayload) (err error)

It’s now up to the developer to implement the expected functionality.

Frontend development

We use openapi-generator-cli to generate the client code after the OpenAPI description of the API. Run make ui-client to generate all the TypeScript code under ui/src/client which is used by the Enduro frontend.

You should see new models and methods added, like the new collectionDelete method:

async collectionDelete(requestParameters: CollectionDeleteRequest): Promise<void> {
    await this.collectionDeleteRaw(requestParameters);
}