Making your first API calls

One of NPL's core advantages is automatic API generation. Every NPL application comes with pre-built API endpoints, OpenAPI specifications, and Swagger UI for testing - no middleware required.

NPL API Overview

NOUMENA Cloud provides several APIs for interacting with your applications:

1. NPL API - The primary API for interacting with NPL protocols (what we'll use today)
2. Engine Streams API - For subscribing to protocol states using Server-Sent Events (SSEs)
3. Engine Management API - For managing application deployment and configuration
4. Engine Multinode API - For multi-node NPL deployments and token management
5. Engine Core API - Legacy API for protocol interaction

On NOUMENA Cloud, the NPL, Streams, Multinode and Core APIs are accessible programmatically under the server base URL

https://engine-{YOUR_TENANT_SLUG}-{YOUR_APPLICATION_SLUG}.noumena.cloud/

For access using a Swagger UI, see below.

Understanding NPL API Endpoints

When you deploy an NPL application with package example.name, these endpoints are automatically generated:

• GET /npl/example/name/-/openapi.json - OpenAPI specification for all endpoints

For each protocol MyProtocol:

• GET /npl/example/name/MyProtocol/ - List all accessible protocol instances
• GET /npl/example/name/MyProtocol/{id} - View a specific instance

For protocols annotated with @api:

• POST /npl/example/name/MyProtocol - Create new protocol instances

For permissions annotated with @api:

• POST /npl/example/name/MyProtocol/myPermission - Execute the specified permission

Testing with Swagger UI

Note

The following assumes you have uploaded the IOU example to your application, but you can follow along with any uploaded NPL package exposing protocols via the @api annotation.

Follow these steps to create your first IOU protocol instance:

1. Access the Swagger UI from your application's Services tab

   

2. Select NPL Application API from the top right dropdown and click Authorize

   

3. In the authorization dialog:

   • Select openid_connect (OAuth2, password)
   • Enter username: alice
   • Enter password: (the password you set for Alice)
   • Enter client_id: (your app slug)
   • Leave client_secret blank
   • Click Login

   

4. Locate and expand the POST /npl/seed/Iou/ endpoint, then click Try it out

   

5. Enter the following JSON in the request body and click Execute:

   {
     "forAmount": 50,
     "@parties": {
       "issuer": {
         "entity": {
           "preferred_username": ["alice"]
         },
         "access": {}
       },
       "payee": {
         "entity": {
           "preferred_username": ["bob"]
         },
         "access": {}
       }
     }
   }

   

   This request creates an IOU protocol where:

   • Alice (issuer) owes 50 units to Bob (payee)
   • Both parties have appropriate access permissions to the protocol

6. You'll receive a response with the protocol details and a unique identifier

   

What Just Happened?

You've successfully:

1. Authenticated as Alice using OAuth2
2. Created an IOU protocol instance where Alice owes Bob 50 units
3. Received confirmation with the protocol's unique ID and status

Exploring Further

Try these additional API calls:

• Log in as Bob and view the IOU using the GET endpoint
• Create additional IOUs with different amounts
• Experiment with other permissions defined in the IOU protocol

Troubleshooting

If you encounter issues:

• Verify Keycloak configuration is correct
• Check user credentials and permissions
• Ensure the request body matches the expected JSON format
• Review the API response for specific error messages

Next Steps

You've successfully deployed your first NPL application, created users, and interacted with it through the automatically generated API. Continue your journey with NOUMENA Cloud by looking into frontends, connectors and further tooling.

If you have any question, you can reach out to the NOUMENA Community.