Skip to content

Using the NPL API with Swagger UI

Prerequisites

Before this track, you should have:

This track uses the npl-init repository as an example.

Accessing Swagger UI

The NPL Runtime provides an interactive Swagger UI interface that allows you to explore and test your NPL API endpoints without writing code. This is particularly useful for:

  • Understanding available API endpoints
  • Testing API calls interactively
  • Exploring request/response schemas
  • Debugging API interactions

Once your NPL application is deployed and running, you can access the Swagger UI by navigating to the NPL Engine API URL.

When running locally the NPL Engine API URL is

http://localhost:12000/

When running on NOUMENA Cloud the NPL Engine API URL can be found on the app overview page.

On NOUMENA Cloud, the Swagger UI is also available from the services tab > Swagger > Visit button.

When running in Codespaces the NPL Engine API URL can be found in the port forwarding tab. See Accessing your application in Codespaces

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

Swagger UI - App dropdown

Authentication in Swagger UI

All access to NPL protocols requires valid JWT tokens. The Swagger UI provides a convenient OIDC login flow for authentication:

  1. In the Swagger UI, click the "Authorize" button (usually located in the top right)
  2. Find the "oidc (OAuth2, password)" authorization section
  3. Enter credentials of an end-user for the NPL application:
    • Username: Enter your username (e.g., alice)
    • Password: Enter your password (e.g., password123)
    • Client ID and Client Secret: On NOUMENA Cloud and locally with ENGINE_DEV_MODE, these are pre-populated and don't need to be changed
  4. Click "Authorize"
  5. Click "Close"

The OIDC flow will automatically handle obtaining and managing your JWT token. Once authorized, all subsequent requests made through the Swagger UI will automatically include your authentication token.

Exploring API Endpoints

The Swagger UI organizes endpoints by protocol. For each protocol annotated with @api, you'll see:

Protocol Creation Endpoints

  • POST /npl/{package-name}/{ProtocolName}/ - Create new protocol instances

Protocol Instance Endpoints

  • GET /npl/{package-name}/{ProtocolName}/ - List all protocol instances
  • GET /npl/{package-name}/{ProtocolName}/{instanceId} - Get specific protocol instance
  • POST /npl/{package-name}/{ProtocolName}/{instanceId}/{permissionName} - Call permissions on protocol instances

Using Swagger UI to Test Your API

Creating a Protocol Instance

  1. Navigate to the protocol creation endpoint (e.g., POST /npl/demo/HelloWorld)
  2. Click "Try it out"
  3. Modify the request body as needed: 
    {
    "@parties": {}
}
  4. Click "Execute"
  5. Review the response, which will include the protocol instance ID

Listing and Viewing Instances

  1. Navigate to the list endpoint (e.g., GET /npl/demo/HelloWorld/)
  2. Click "Try it out"
  3. Click "Execute" to see all instances you have access to
  4. Use the instance view endpoint to examine specific instances in detail

Calling Permissions

  1. Copy the instance ID from the creation response
  2. Navigate to the permission endpoint (e.g., POST /npl/demo/HelloWorld/{instanceId}/sayHello)
  3. Click "Try it out"
  4. Enter the instance ID in the instanceId parameter field
  5. Provide any required request body parameters
  6. Click "Execute"
  7. Review the response

Understanding Request/Response Schemas

The Swagger UI provides detailed schema information for each endpoint:

  • Request schemas show the expected structure of request bodies
  • Response schemas show what data will be returned
  • Parameter documentation explains path parameters, query parameters, and headers
  • Examples provide sample requests and responses

Click on any schema section to expand it and see the full structure with data types and descriptions.

Tips for Using Swagger UI

  • Use the "Models" section at the bottom to understand complex data structures
  • Check response codes to understand different success and error scenarios
  • Use the "Download" button to export API specifications for external tools
  • Test edge cases by modifying request parameters and observing responses
  • Copy curl commands using the "Copy" button for use in scripts or external tools

Troubleshooting Common Issues

Authentication Problems

  • Ensure your JWT token is valid and not expired. If your token is expired, go again through the Swagger UI authentication step.
  • Verify that the user has appropriate permissions for the protocol operations

Missing endpoint

  • Confirm that your protocol or permission is annotated with @api
  • Verify that the protocol has been successfully deployed

Permission Errors

  • Ensure the user matches a role authorized for the specific protocol instance and permission. For more details, check party model

Next Steps

After successfully using the Swagger UI to interact with your NPL API, you might want to:

Further Reading