Make 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

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

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

Congratulations!

You've successfully deployed your first NPL application, created users, and interacted with it through the automatically generated API. This completes the getting started guide for NOUMENA Cloud.

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