{
  "openapi": "3.1.0",
  "info": {
    "title": "Ever After Books public catalogue",
    "version": "1.0.0",
    "description": "Read-only catalogue search. Follow product URLs to select a variant and order through normal checkout. Shipping and the final total are confirmed at checkout. Results can be cached for 60 seconds."
  },
  "servers": [
    {
      "url": "https://everafterbooks.uk"
    }
  ],
  "security": [],
  "externalDocs": {
    "url": "https://everafterbooks.uk/agents"
  },
  "paths": {
    "/api/search/products": {
      "get": {
        "operationId": "searchBooks",
        "summary": "Search by title, author or catalogue tag",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "example": "Jane Austen"
          }
        ],
        "responses": {
          "200": {
            "description": "Up to 20 matching products. No matches is an empty products array.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "products",
                    "query",
                    "count"
                  ],
                  "properties": {
                    "products": {
                      "type": "array",
                      "maxItems": 20,
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "gid": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "handle": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "variantId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "barcode": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Supplier barcode for the first variant, often an ISBN for a book. May be absent."
                          },
                          "description": {
                            "type": "string"
                          },
                      "author": {
                        "type": "string"
                      },
                      "publisher": {
                        "type": "string"
                      },
                          "coverUrl": {
                            "type": "string"
                          },
                          "price": {
                            "type": "number"
                          },
                          "currency": {
                            "type": "string",
                            "description": "ISO 4217 currency code. Do not assume a destination currency."
                          },
                          "availableForSale": {
                            "type": "boolean",
                            "description": "Availability for the priced first variant. Does not guarantee delivery to a particular address."
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "productType": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "query": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "shippingPolicy": {
                      "type": "string",
                      "format": "uri"
                    },
                    "returnsPolicy": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Query exceeds 200 characters"
          },
          "500": {
            "description": "Catalogue search is temporarily unavailable"
          }
        }
      }
    }
  }
}