Skip to content

Using your NPL application

Prerequisites

Before this track, you should have:

This track uses the npl-init repository as an example. Follow the Developing NPL on your own machine track to download it on your machine.

Authentication and Authorization

All access to protocols is governed by valid JWT tokens and subject to strong authorization. In development mode, the engine includes an embedded OIDC server. To set up an IAM production, follow the setting up an IAM with Keycloak how-to guide.

When interacting with your NPL application:

  1. Ensure you have a valid JWT token for authentication

    On Unix-based systems and Windows with WSL

    export ACCESS_TOKEN=$(curl -s 'http://localhost:11000/token' \
    -d 'username=alice' \
    -d 'password=password123' \
    -d 'grant_type=password' | \
    sed -n 's/."access_token":"\([^"]*\)".*/\1/p')

    On Windows without WSL

    $env:ACCESS_TOKEN = (curl -s 'http://localhost:11000/token'\
    -d 'username=alice' \
    -d 'password=password123' \
    -d 'grant_type=password' | \
    ConvertFrom-Json).access_token

  2. Include the token in the Authorization header of your requests (see various examples below)

  3. The token is used to check read and update rights on each protocol instance individually according to the party model

    Use exclusively the preferred_username or email address in party entity claims for a simple start with the party model.

In swagger, you can use the "Authorize" button and scroll to jwt (http, Bearer) authorization to enter your JWT token. This will automatically authorise all requests in that swagger UI session.

Exposing protocols for creation

The @api annotation is used to expose a protocol as a service. This allows you to create protocol instances from outside the NPL Runtime through RESTful API endpoints.

To expose a protocol via API, annotate it with the @api annotation:

package demo;

@api
protocol[innovator] HelloWorld() {

};

Once your protocols are annotated with @api and deployed to the NOUMENA Runtime, they become accessible via REST endpoints at:

POST /npl/{package-name}/{ProtocolName}

For example, if your protocol is named HelloWorld in the package demo, the endpoint would be:

POST /npl/demo/HelloWorld

You can find all available endpoints for the demo package by accessing the Swagger UI at

http://localhost:12000/swagger-ui/?urls.primaryName=NPL Application - demo

If you have deployed sources belonging to multiple packages, you can select the package you want to explore from the dropdown menu in the top right corner.

Creating a protocol instance

To instantiate a protocol, you'll need to make a POST request to the protocol's endpoint with the parameters from the constructor of the protocol:

POST /npl/demo/HelloWorld

Request body:

{
  "@parties": {}
}

To call the create protocol endpoint, you need to provide the required parameters in the request body and the authorization as header.

curl -X POST -H 'accept: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{ "@parties": {}}' \
    http://localhost:12000/npl/demo/HelloWorld/

The response will include the protocol instance ID which you can use for subsequent operations. ^

You may also observe in the response that some values have been bound to the party "innovator", although the @parties argument in the request was empty. This stems from the party rules specified in file ./src/main/rules/rules_1.0.0.yml.

Calling permissions on your NPL protocol instances

Just like protocols, permissions can also be exposed via the API using the @api annotation:

package demo;

@api
protocol[innovator] HelloWorld() {

    initial state greeting;
    final state greeted;

    @api
    permission[innovator] sayHello() returns Text | greeting {
        become greeted;
        return "Hello " + getUsername(innovator) + "!";
    };
};

Once deployed, you can invoke these permissions via HTTP endpoints:

POST /npl/{package-name}/{ProtocolName}/{instanceId}/{permissionName}

For example, to call the sayHello permission on a HelloWorld instance:

POST /npl/demo/HelloWorld/{instanceId}/sayHello

The full curl request would look like this (replace instanceId with the actual ID):

curl -X POST -H 'accept: application/json' -H "Authorization: Bearer $ACCESS_TOKEN" \
  http://localhost:12000/npl/demo/HelloWorld/{instanceId}/sayHello

Listing and viewing protocol instances

To list all protocol instances you have access to:

GET /npl/{package-name}/{ProtocolName}/

The full curl request would look like this:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  http://localhost:12000/npl/demo/HelloWorld/

To view a specific protocol instance:

GET /npl/{package-name}/{ProtocolName}/{instanceId}

The full curl request would look like this:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  http://localhost:12000/npl/demo/HelloWorld/{instanceId}/

Next steps

After successfully interacting with your NPL application, you might want to:

Further reading