NPL application definition missing from engine swagger-ui when no protocol has @api annotation

Noumena Runtime
,
1

PLATFORM_VERSION=2024.2.2

Given that only certain permissions are annotated with @api but none of the protocols, then the swagger-ui NPL application definition is missing. I would expect my exposed api’s to be there. Am I missing something?

2

I believe codegen for permissions requires not only that the permission itself be @api-annotated, but also the protocol to which it belongs. Do you have a particular use-case where this is not desirable?

3

Indeed there might be. I am setting up a project in which a front-end is talking directly to npl without an intermediate api layer. Therefore I want to limit the possibility for just anyone to be able to create protocols in npl.

See also: Restrict Protocol creation

4

Thanks for reporting it Lukas!

From my testing, here is what comes around

  1. Scenario 1: 1 protocol with protocol-level @api annotation
    Result: the protocol has an endpoint up in the NPL API, :white_check_mark: @api permissions too :white_check_mark:

  2. Scenario 2: 1 protocol without protocol-level @api annotation, with @api annotated permissions
    Result:
    The package does not show up in the list of open-api specs :x:
    The @api annotated permissions should be sufficient to create the file, and permissions to be created, see Log in with Atlassian account

  3. Scenario 3: 2 protocols, only one with @api annotation, each having @api annotated permissions
    Result:
    The @api annotated protocol has a create endpoint, the other one doesn’t :white_check_mark:
    @api annotated permissions are shown in the file :white_check_mark:

  4. Scenario 4: same as (3) but protocols are in different files
    Step 1: instantiate the protocol that does not have an open-api file available (for example through another protocol)
    Step 2: call the get and action endpoints on the no-open-api-file protocol
    Result: Endpoints exists, while the file doesn’t :x:

In your case, you are likely using the npl-run in your migration to create one or more protocols and want to call permissions on these, yet the whole file is missing.

Your use-case is valid, and only the open-api file is missing. The actual endpoints are available.
I will file a ticket to fix this logic and come back to you.

In the meantime, you can solve the issue by adding a protocol declaration that does not affect your system. Make sure to have the same package as the notifications you want to see appear. E.g.

@api
protocol[p] Foo() {
    require(1 == 2, "This will always fail");
};
1 Like
5

Is it possible to control whether @api generates only GET or POST

6

Hi Eric,

For each protocol MyProtocol, the API supports:

  • GET /npl/example/name/MyProtocol/ for listing instances the caller has access to;
  • GET /npl/example/name/MyProtocol/{id} for viewing a specific instance;

In addition, for each protocol MyProtocol annotated with @api, the API supports:

  • POST /npl/example/name/MyProtocol for creating new instances;

So the @api controls if the POST endpoint to create protocol instances is available, whereas the GET endpoints to read protocol instances will be available for all protocols.

7

We’ve merged a fix for this now, which will be available in the next release (2024.2.4).

1 Like