Using your NPL application

Prerequisites

Before this track, you should have:

Completed the developing your NPL application track
Installed the jq library
```
brew install jq
```
Made sure the NOUMENA Runtime is running on your own machine:

Use docker ps to see running containers. The status of the engine should be "Up".

If not, revisit the developing your NPL application track

This track uses the npl-init repository as an example. Follow the developing your NPL application 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:

Ensure you have a valid JWT token for authentication

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

Include the token in the Authorization header of your requests
The token is used to check read and update rights on each protocol instance individually according to the party model > Use exclusively the email address in party entity claims for a simple start with the party model.

In swagger, you can use the "Authorize" button to enter your JWT token. This will automatically add the token to the Authorization header for all requests.

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 counter;

@api
protocol[user] Counter(var target: Number) {

};

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 Counter in the package counter, the endpoint would be:

POST /npl/counter/Counter

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

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

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/counter/Counter

Request body:

{
  "target": 5,
  "@parties": {
    "user": {
      "entity": {
        "preferred_username": [
          "alice"
        ]
      },
      "access": {}
    }
  }
}

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 '{ "target": 5, "@parties": { "user": { "entity": { "preferred_username": [ "alice" ] }, "access": {} }}}' \
http://localhost:12000/npl/counter/Counter/

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

Calling permissions on your NPL protocol instances

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

package counter;

@api
protocol[user] Counter(var target: Number) {

    initial state counting;

    @api
    permission[user] increment() | counting {

    };
};

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

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

For example, to call the increment permission on a Counter instance:

POST /npl/counter/Counter/{instanceId}/increment

Request body:

{
  "amount": 50
}

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/counter/Counter/{instanceId}/increment

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/counter/Counter

To view a specific protocol instance:

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