Gutendex API — Books

naftiko: 1.0.0-alpha2
info:
  label: Gutendex API — Books
  description: 'Gutendex API — Books. 2 operations: List Books and Get Book. Self-contained
    Naftiko capability covering the full Gutendex public API surface for Project Gutenberg
    ebook metadata.'
  tags:
    - Gutendex
    - Books
    - Project Gutenberg
  created: '2026-05-29'
  modified: '2026-05-29'
binds: []
capability:
  consumes:
    - type: http
      namespace: gutendex-books
      baseUri: https://gutendex.com
      description: Gutendex API — Books business capability. Self-contained, no shared references. No authentication required.
      resources:
        - name: books
          path: /books
          operations:
            - name: listBooks
              method: GET
              description: List Books
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: author_year_start
                  in: query
                  type: integer
                  description: Find books with at least one author alive on or after this year.
                  required: false
                - name: author_year_end
                  in: query
                  type: integer
                  description: Find books with at least one author alive on or before this year.
                  required: false
                - name: copyright
                  in: query
                  type: string
                  description: Filter by copyright status (true, false, null).
                  required: false
                - name: ids
                  in: query
                  type: string
                  description: Comma-separated Project Gutenberg IDs.
                  required: false
                - name: languages
                  in: query
                  type: string
                  description: Comma-separated two-character language codes.
                  required: false
                - name: mime_type
                  in: query
                  type: string
                  description: Prefix-matched MIME type.
                  required: false
                - name: search
                  in: query
                  type: string
                  description: Space-separated keywords for authors and titles.
                  required: false
                - name: sort
                  in: query
                  type: string
                  description: Sort order (popular, ascending, descending).
                  required: false
                - name: topic
                  in: query
                  type: string
                  description: Case-insensitive search across bookshelves and subjects.
                  required: false
        - name: book
          path: /books/{id}
          operations:
            - name: getBook
              method: GET
              description: Get Book
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: id
                  in: path
                  type: integer
                  description: Project Gutenberg ID number of the book.
                  required: true
      authentication:
        type: none
  exposes:
    - type: rest
      namespace: gutendex-books-rest
      port: 8080
      description: REST adapter for Gutendex API — Books. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/books
          name: books
          description: REST surface for listing Project Gutenberg books.
          operations:
            - method: GET
              name: listBooks
              description: List Books
              call: gutendex-books.listBooks
              with:
                author_year_start: rest.query.author_year_start
                author_year_end: rest.query.author_year_end
                copyright: rest.query.copyright
                ids: rest.query.ids
                languages: rest.query.languages
                mime_type: rest.query.mime_type
                search: rest.query.search
                sort: rest.query.sort
                topic: rest.query.topic
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/books/{id}
          name: book
          description: REST surface for retrieving a single Project Gutenberg book by ID.
          operations:
            - method: GET
              name: getBook
              description: Get Book
              call: gutendex-books.getBook
              with:
                id: rest.path.id
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: gutendex-books-mcp
      port: 9090
      transport: http
      description: MCP adapter for Gutendex API — Books. One tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: gutendex-list-books
          description: List Books from Project Gutenberg with optional filters.
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: gutendex-books.listBooks
          with:
            author_year_start: tools.author_year_start
            author_year_end: tools.author_year_end
            copyright: tools.copyright
            ids: tools.ids
            languages: tools.languages
            mime_type: tools.mime_type
            search: tools.search
            sort: tools.sort
            topic: tools.topic
          outputParameters:
            - type: object
              mapping: $.
        - name: gutendex-get-book
          description: Get a single Project Gutenberg book by ID.
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: gutendex-books.getBook
          with:
            id: tools.id
          outputParameters:
            - type: object
              mapping: $.