NPL application APIs

When deploying an NPL application, the NOUMENA Operating Engine automatically instantiates multiple endpoints and OpenAPI specifications to expose a REST API for your application.

You can explore these APIs via Swagger UI, available by default at http://localhost:12000/swagger-ui/.

Outline

The NPL APIs provide a canonical view on the underlying NPL protocols. The @api annotation is used to determine which operations are exposed by the API.

All access to the various protocols is governed by the usual valid JWT token and subject to the usual strong authorization.

Endpoints

For each package example.name in your application, the NOUMENA Operating Engine automatically instantiates multiple endpoints under the path /npl/example/name.

First of all, it supports:

• GET /npl/example/name/-/openapi.json, which is the OpenAPI specification for all instantiated endpoints.

Then, for each protocol MyProtocol, it supports:

• GET /npl/example/name/MyProtocol/ for listing instances the caller has access to;
• GET /npl/example/name/MyProtocol/{id} for viewing a specific instance;

In addition, for each protocol MyProtocol annotated with @api, it supports:

• POST /npl/example/name/MyProtocol for creating new instances

Finally, for each action MyProtocol.myPermission annotated with @api it supports:

• POST /npl/example/name/MyProtocol/myPermission for calling the specified permission.

Actions that return Unit in NPL, return the protocol itself on the endpoints.

OpenAPI specification

All endpoints mentioned above are described by the OpenAPI specification, which also provides an extensive JSON Schema for the various types expressed in NPL.

The OpenAPI specification is designed to support automated generated client code through tools such as the OpenAPI Generator.