Using your NPL application
Prerequisites
Before this track, you should have:
- Completed the Developing NPL on your own machine track
-
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 NPL on your own machine track.
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:
-
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
-
Include the token in the Authorization header of your requests (see various examples below)
-
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:
- Deploy your application to NOUMENA Cloud
- Explore more advanced protocol patterns
- Integrate your NPL application with other services
- Set up an IAM with Keycloak