API Definitions (.nornapi)

.nornapi files define reusable header groups and named endpoints. Import them into your .norn files to keep requests shorter and more consistent.

Basic .nornapi File

headers Json
Content-Type: application/json
Accept: application/json
end headers

headers Auth
Authorization: Bearer {{token}}
end headers

endpoints
    GetTodo: GET {{baseUrl}}/todos/{id}
    CreateTodo: POST {{baseUrl}}/todos
    GetUserPosts: GET {{baseUrl}}/users/{userId}/posts
end endpoints

Path parameters use {id} syntax. Regular variables still use {{name}} syntax. Use {{$env.name}} when an endpoint URL or header group must read directly from the active environment.

Importing and Using Definitions

import "./api.nornapi"

GET GetTodo(1) Json

POST CreateTodo Json Auth
{
    "title": "Write docs",
    "completed": false
}

var userId = 3
GET GetUserPosts({{userId}}) Json

The endpoint name comes from the endpoints block, while header groups come from the headers blocks you imported.

Header Groups

Apply header groups on the request line or on separate lines. You can stack multiple groups together.

import "./api.nornapi"

# Same line
GET GetTodo(1) Json Auth

# Separate lines
GET GetTodo(2)
Json
Auth

# Header groups also work with raw URLs
GET {{baseUrl}}/todos/3
Json

Inline headers in the request override the same header from a header group when you need a one-off value.

Endpoint Parameters

Endpoint calls support positional arguments and named arguments with :.

import "./api.nornapi"

# Positional
GET GetTodo(5) Json

# Named
GET GetTodo(id: 6) Json

var currentUserId = 7
GET GetUserPosts(userId: {{currentUserId}}) Json

Swagger / OpenAPI Import

You can keep a Swagger or OpenAPI source URL in the file and use the VS Code tooling to generate endpoint definitions from it.

swagger "https://petstore.swagger.io/v2/swagger.json"

In VS Code, use Import Endpoints on that line to generate an endpoints block you can commit and reuse. The runner uses the generated endpoint definitions in the file at execution time.

Rules to Remember

• Import the .nornapi file from your .norn file before using its endpoints or header groups.
• Endpoint names and header group names are case-sensitive.
• Use {param} for endpoint path parameters and {{variable}} for regular variable substitution.
• Multiple .nornapi files can be imported, but duplicate endpoint or header-group names will conflict.