Tutorial

Introduction

Welcome to the tutorial for Naftiko Framework. Starting with the simplest "Hello World!" capability, it offers a hands-on, progressive journey to learn some on the key features offered to do Spec-Driven Integration.

Please read the installation instructions to know how to run the Naftiko Engine with your capability file.

1. My first capability

Start with a very basic capability returning "Hello, World!", using only an API server adapter with constants.

naftiko: "0.4"
info:
  label: "Tutorial - Step 1 - Hello, World!"
  description: "This is a sample capability specification to demonstrate the features of Naftiko"
  tags:
    - Naftiko
    - Tutorial
  created: "2026-02-26"
  modified: "2026-03-03"
  stakeholders:
    - role: "editor"
      fullName: "Navi"
      email: "navi@naftiko.io"

capability:
  exposes:
    - type: "api"
      port: 8081
      namespace: "tutorial"
      resources:
        - path: "/hello"
          name: "hello"
          label: "My first resource"
          description: "This is a resource to demonstrate a simple Hello, World! API endpoint"
          operations:
            - method: "GET"
              outputParameters:
                - type: "string"
                  const: "Hello, World!"

Then run the Naftiko Engine with this capability, and execute a GET request on http://localhost:8081/hello.
It should display the following JSON response

{
  "value": "Hello, World!"
}

Congrats, you ran your first capability!

2. Forwarding API resource

Add a "consumes" section to forward an existing API (Notion API in our example) and expose it as a capability.

naftiko: "0.4"
info:
  label: "Tutorial - Step 2 - Forwarding API Resource"
  description: "This is a sample capability specification to demonstrate the features of Naftiko"
  tags:
    - Naftiko
    - Tutorial
  created: "2026-02-26"
  modified: "2026-03-03"
  stakeholders:
    - role: "editor"
      fullName: "Navi"
      email: "navi@naftiko.io"

capability:
  exposes:
    - type: "api"
      port: 8081
      namespace: "sample"
      resources:
        - path: "/notion/{{path}}"
          description: "This resource forwards requests to the Notion API, allowing access to any Notion endpoint by specifying the path parameter. For example, a request to /notion/pages would be forwarded to https://api.notion.com/v1/pages."
          forward:
            targetNamespace: notion
            trustedHeaders:
            - Notion-Version

  consumes:
    - type: "http"
      description: "Forwarded requests from the /notion/{path} resource, to be sent to the Notion API"
      namespace: "notion"
      baseUri: "https://api.notion.com/v1/"

Execute a GET request on http://localhost:8081/notion/users/me. You must add a "Authorization: Bearer your_notion_api_key" and a "Notion-Version: 2025-09-03" header. Note the {{path}} keyword that allows you to access all API resources (and not only the /users/me of this example). The value of the keyword will be paste after https://api.notion.com/v1/
It should display a JSON response similar to:

{
  "object": "user",
  "id": "9c1061dc-0350-4aa0-afb0-xxxxxxxxxxxx",
  "name": "Capability",
  "avatar_url": null,
  "type": "bot",
  "bot": {
    "owner": {
      "type": "workspace",
      "workspace": true
    },
    "workspace_name": "Naftiko",
    "workspace_id": "39d4adce-3d02-81a1-afeb-xxxxxxxxxxxx",
    "workspace_limits": {
      "max_file_upload_size_in_bytes": 5368709120
    }
  },
  "request_id": "a3d33d51-d51f-4f3b-a616-xxxxxxxxxxxx"
}

3. Encapsulating HTTP source

Let's say you don't want to add headers when requesting the capability. For that you can define these headers as input parameters in the "consumes" section.

naftiko: "0.4"
info:
  label: "Tutorial - Step 3b - Forwarding API Resource"
  description: "This is a sample capability specification to demonstrate the features of Naftiko"
  tags:
    - Naftiko
    - Tutorial
  created: "2026-02-26"
  modified: "2026-03-03"
  stakeholders:
    - role: "editor"
      fullName: "Navi"
      email: "navi@naftiko.io"

capability:
  exposes:
    - type: "api"
      port: 8081
      namespace: "sample"
      resources:
        - path: "/notion/{{path}}"
          description: "This resource forwards requests to the Notion API, allowing access to any Notion endpoint by specifying the path parameter. For example, a request to /notion/pages would be forwarded to https://api.notion.com/v1/pages."
          forward:
            targetNamespace: notion
            trustedHeaders:
            - Notion-Version

  consumes:
    - type: "http"
      description: "Forwarded requests from the /notion/{path} resource, to be sent to the Notion API"
      namespace: "notion"
      baseUri: "https://api.notion.com/v1/"
      authentication:
        type: "bearer"
        token: "{{notion_api_key}}"
      inputParameters:
        - name: "notion_api_key"
          in: "environment"
        - name: "Notion-Version"
          in: "header"
          const: "2025-09-03"

IDEA: Remove the need to forward the Notion-Version header and the authentication credential via the API server adapter, encapsulating those in the HTTP client adapter.

IDEA: Instead of setting up the Notion API key manually in the YAML, pass it via an environment variable with proper "in" value ("environment")

4. Structured API resource

IDEA: Define a capability that turns a generic Notion API data source into a proper domain API

IDEA: Adapt a read-only POST query into a cacheable GET query, a pretty powerful mini use case

5. Declarative MCP tools

IDEA: Expand the tutorial to expose an MCP server adapter, first using default "Stdio" transport and VS Code as an example local MCP client IDEA: As step 5b, expose via Streaming HTTP transport as an example of remote MCP client use case

6. Multi-steps implementation

IDEA: ?

7. Raw data conversion

IDEA: ?

8. Multi-sources capability

IDEA: ?

9. Advanced lookup

IDEA: ?