swagger.v1.1.x.json

{
  "swagger": "2.0",
  "info": {
    "version": "1.1.1",
    "title": "Discovery API",
    "description": "NYPL research holdings as linked data"
  },
  "host": "platform.nypl.org",
  "basePath": "/api",
  "schemes": [
    "https"
  ],
  "tags": [
    {
      "name": "discovery",
      "description": "Discovery API"
    }
  ],
  "paths": {
    "/v0.1/discovery/resources": {
      "get": {
        "tags": [
          "discovery"
        ],
        "summary": "Search resources (bibs and items)",
        "description": "Match by keyword\n> `/resources?q=war peace`\n\nFilters are applied using a `filters` param that expects this syntax on the query string:\n\n> `/resources?filters[property1]=value1&filters[property2]=value2`\n\nWhere `property*` is one of: \n\n> 'owner', 'buildingLocation', 'subjectLiteral', 'holdingLocation', 'deliveryLocation', 'language', 'materialType', 'mediaType', 'carrierType', 'publisher', 'contributor', 'creator', 'issuance', 'createdYear', 'dateAfter', or 'dateBefore'.\n\nSee [the app README for more examples](https://github.com/NYPL/discovery-api/blob/main/README.md)\n",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Terms to match (and/or structured ES \"Query String Query\" https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax )",
            "required": false,
            "type": "string"
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number to return",
            "required": false,
            "type": "integer",
            "default": 1,
            "minimum": 1
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of results to return",
            "required": false,
            "type": "integer",
            "default": 50,
            "maximum": 100,
            "minimum": 1
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Specify how to order results (relevance, title, creator, date)",
            "required": false,
            "type": "string",
            "enum": [
              "relevance",
              "title",
              "creator",
              "date"
            ],
            "default": "relevance"
          },
          {
            "name": "sort_direction",
            "in": "query",
            "description": "Override the default direction for the current sort (asc, desc). Default depends on the field. (title defaults to asc, date defaults to desc, creator defaults to asc, relevance is fixed desc)",
            "required": false,
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ]
          },
          {
            "name": "search_scope",
            "in": "query",
            "description": "Specify what (group of) fields to match against (all, title, contributor, subject, series, callnumber, standard_number). See https://github.com/NYPL/discovery-api/blob/main/lib/resources.js to review specific fields matched in each scope and how they're boosted.",
            "required": false,
            "type": "string",
            "enum": [
              "all",
              "title",
              "journal_title",
              "contributor",
              "subject",
              "series",
              "callnumber",
              "standard_number"
            ],
            "default": "all"
          },
          {
            "name": "filters[*]",
            "in": "query",
            "description": "Specify a hash of filters to apply, where key is: 'recordType', 'buildingLocation', 'owner', 'subjectLiteral', 'holdingLocation', 'deliveryLocation', 'language', 'materialType', 'mediaType', 'carrierType', 'publisher', 'contributor', 'creator', 'issuance', 'createdYear', 'dateAfter', or 'dateBefore'",
            "required": false,
            "type": "string"
          },
          {
            "name": "contributor",
            "type": "string",
            "in": "query",
            "description": "Fuzzy match on contributor name"
          },
          {
            "name": "title",
            "type": "string",
            "in": "query",
            "description": "Fuzzy match on title"
          },
          {
            "name": "subject",
            "type": "string",
            "in": "query",
            "description": "Fuzzy match on subject"
          },
          {
            "name": "isbn",
            "type": "string",
            "in": "query",
            "description": "Match on ISBN"
          },
          {
            "name": "issn",
            "type": "string",
            "in": "query",
            "description": "Match on ISSN"
          },
          {
            "name": "lccn",
            "type": "string",
            "in": "query",
            "description": "Match on LCCN"
          },
          {
            "name": "oclc",
            "type": "string",
            "in": "query",
            "description": "Match on OCLC number"
          }
        ],
        "responses": {
          "200": {
            "description": "An array of resources",
            "schema": {
              "$ref": "#/definitions/ResourcesResponse"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/ResourceError"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:224280085904:function:discovery-api/invocations",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws_proxy",
          "cacheKeyParameters": [
            "method.request.querystring.q",
            "method.request.querystring.search_scope",
            "method.request.querystring.page",
            "method.request.querystring.per_page",
            "method.request.querystring.sort",
            "method.request.querystring.sort_direction"
          ]
        }
      }
    },
    "/v0.1/discovery/resources/{id}": {
      "get": {
        "summary": "Fetch a resource by ID",
        "description": "Fetch a resource. Note alternate response formats:\n\n`.ntriples, .turtle, .jsonld (default)`\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID",
            "required": true,
            "type": "string"
          },
          {
            "name": "items_size",
            "in": "query",
            "description": "Specify many items to return",
            "default": 100,
            "type": "number"
          },
          {
            "name": "items_from",
            "type": "number",
            "in": "query",
            "description": "Specify starting index for retrieved items",
            "default": 0
          },
          {
            "name": "all_items",
            "type": "boolean",
            "in": "query",
            "description": "When true, fetches all items for a bib. Overrides items_from and items_size",
            "default": false
          },
          {
            "name": "item_location",
            "type": "string",
            "in": "query",
            "description": "Filter on item location"
          },
          {
            "name": "item_status",
            "type": "string",
            "in": "query",
            "description": "Filter on item status"
          },
          {
            "name": "item_format",
            "type": "string",
            "in": "query",
            "description": "Filter on item format"
          }
        ],
        "tags": [
          "discovery"
        ],
        "responses": {
          "200": {
            "description": "A single resource",
            "schema": {
              "$ref": "#/definitions/Resource"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/ResourceError"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:224280085904:function:discovery-api/invocations",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws_proxy",
          "cacheKeyParameters": [
            "method.request.path.id"
          ]
        }
      }
    },
    "/v0.1/discovery/resources/aggregations": {
      "get": {
        "tags": [
          "discovery"
        ],
        "summary": "Resource Search Aggregations",
        "description": "Fetch resources search aggregations.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Terms to match (and/or structured ES \"Query String Query\" https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax )",
            "required": true,
            "type": "string"
          },
          {
            "name": "search_scope",
            "in": "query",
            "description": "Specify what (group of) fields to match against",
            "required": false,
            "type": "string",
            "enum": [
              "all",
              "title",
              "journal_title",
              "contributor",
              "subject",
              "series",
              "callnumber"
            ],
            "default": "all"
          },
          {
            "name": "filters[*]",
            "in": "query",
            "description": "Specify a hash of filters to apply, where key is: 'buildingLocation', 'owner', 'subjectLiteral', 'holdingLocation', 'deliveryLocation', 'language', 'materialType', 'mediaType', 'carrierType', 'publisher', 'contributor', 'creator', 'issuance', 'createdYear', 'dateAfter', or 'dateBefore'",
            "required": false,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "An array of resources search aggregations",
            "schema": {
              "$ref": "#/definitions/ResourceAggregationsResponse"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/ResourceError"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:224280085904:function:discovery-api/invocations",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws_proxy",
          "cacheKeyParameters": [
            "method.request.querystring.q",
            "method.request.querystring.search_scope",
            "method.request.querystring.filters",
            "method.request.querystring.per_page"
          ]
        }
      }
    },
    "/v0.1/discovery/resources/aggregation/{id}": {
      "get": {
        "summary": "Get a specific resources aggregation",
        "description": "Fetch a specific resources search aggregation. This provides ability to consume the long tail of values for a given aggregation.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "Identifies field being aggregated, e.g. \"language\""
          },
          {
            "name": "q",
            "in": "query",
            "description": "Terms to match (and/or structured ES \"Query String Query\" https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax )",
            "required": false,
            "type": "string"
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number to return",
            "required": false,
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of results to return",
            "required": false,
            "type": "integer",
            "default": 50,
            "maximum": 100,
            "minimum": 1
          },
          {
            "name": "search_scope",
            "in": "query",
            "description": "Specify what (group of) fields to match against",
            "required": false,
            "type": "string",
            "enum": [
              "all",
              "title",
              "contributor",
              "subject",
              "series",
              "callnumber"
            ],
            "default": "all"
          }
        ],
        "tags": [
          "discovery"
        ],
        "responses": {
          "200": {
            "description": "An array of resources search aggregations",
            "schema": {
              "$ref": "#/definitions/ResourceAggregationResponse"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/ResourceError"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:224280085904:function:discovery-api/invocations",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws_proxy",
          "cacheKeyParameters": [
            "method.request.querystring.q",
            "method.request.querystring.search_scope",
            "method.request.querystring.page",
            "method.request.querystring.per_page",
            "method.request.querystring.sort",
            "method.request.querystring.sort_direction",
            "method.request.path.id"
          ],
          "contentHandling": "CONVERT_TO_TEXT"
        }
      }
    },
    "/v0.1/request/deliveryLocationsByBarcode": {
      "get": {
        "summary": "Get items mapped to deliveryLocation(s) by barcode(s)",
        "description": "Accepts multiple item barcodes, returns a special serialization of those items with an array of deliveryLocation objects.",
        "parameters": [
          {
            "name": "barcodes[]",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "Item barcode(s) to match. There can be multiple of them (e.g ?barcodes[]=123&barcodes[]=456)"
          },
          {
            "name": "patronId",
            "in": "query",
            "type": "string",
            "description": "Patron ID, whose patron type will govern visibility of certain delivery locations."
          }
        ],
        "tags": [
          "request"
        ],
        "responses": {
          "200": {
            "description": "An array of items",
            "schema": {
              "$ref": "#/definitions/Item"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/ResourceError"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "GET",
          "type": "http",
          "cacheKeyParameters": [
            "method.request.querystring.barcodes",
            "method.request.querystring.patronId"
          ],
          "contentHandling": "CONVERT_TO_TEXT"
        },
        "security": [
          {
            "api_auth": [
              "read:patron"
            ]
          }
        ]
      }
    }
  },
  "definitions": {
    "ResourcesResponse": {
      "type": "object",
      "properties": {
        "@context": {
          "type": "string",
          "format": "url",
          "description": "URL for JSONLD doc mapping short-hand property names to IRIs"
        },
        "@type": {
          "type": "string",
          "enum": [
            "itemList"
          ]
        },
        "itemListElement": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ResourceResult"
          }
        }
      }
    },
    "ResourceResult": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string",
          "enum": [
            "searchResult"
          ]
        },
        "result": {
          "$ref": "#/definitions/Resource"
        }
      }
    },
    "ResourceAggregationsResponse": {
      "type": "object",
      "properties": {
        "@context": {
          "type": "string",
          "format": "url",
          "description": "URL for JSONLD doc mapping short-hand property names to IRIs"
        },
        "@type": {
          "type": "string",
          "enum": [
            "itemListElement"
          ]
        },
        "@id": {
          "type": "string",
          "description": "ID, e.g. \"language\""
        },
        "itemListElement": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Aggregation"
          }
        }
      }
    },
    "ResourceAggregationResponse": {
      "type": "object",
      "properties": {
        "@context": {
          "type": "string",
          "format": "url",
          "description": "URL for JSONLD doc mapping short-hand property names to IRIs"
        },
        "@type": {
          "type": "string",
          "enum": [
            "itemListElement"
          ]
        },
        "item": {
          "$ref": "#/definitions/Aggregation"
        }
      }
    },
    "Resource": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "RDF type(s), e.g. \"nypl:Item\", \"nypl:Resource\""
        },
        "@id": {
          "type": "string",
          "description": "ID, e.g. \"res:105173159\""
        },
        "carrierType": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "creatorLiteral": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Creator literals"
        },
        "contributorLiteral": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Contributor literals"
        },
        "created": {
          "type": "string",
          "description": "Raw, unparsed date string"
        },
        "createdYear": {
          "type": "integer",
          "description": "Year of creation"
        },
        "dateStartYear": {
          "type": "integer",
          "description": "Start of relevant year range"
        },
        "depiction": {
          "type": "string",
          "description": "URL of an image for the resource"
        },
        "description": {
          "type": "string",
          "description": "Description of resource"
        },
        "endYear": {
          "type": "integer",
          "description": "Ending year of coverage"
        },
        "extent": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Extent (e.g. page count)"
        },
        "holdingCount": {
          "type": "integer",
          "description": "Rough number of copies across institutions"
        },
        "issuance": {
          "type": "array",
          "description": "Issuance",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "items": {
          "type": "array",
          "description": "Array of items attached to this bib",
          "items": {
            "$ref": "#/definitions/Item"
          }
        },
        "^id": {
          "type": "string",
          "description": "Various identifiers given as 'idAcqnum', 'idBarcode', 'idBnum', 'idCallNum', 'idCatnyp', 'idDcc', 'idExhib', 'idHathi', 'idIsbn', 'idIssn', 'idLcc', 'idLccCoarse', 'idMmmsDb', 'idMss', 'idObjNum', 'idOclc', 'idOwi', 'idRlin', 'idUuid'"
        },
        "language": {
          "type": "array",
          "description": "Language(s), if known",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "materialType": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "mediaType": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "note": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "@type": {
                "type": "string",
                "enum": [
                  "bf:Note"
                ]
              },
              "noteType": {
                "type": "string",
                "description": "One of roughly 47 categories of notes (e.g. General Note, Dissertation Note, Data Quality Note., etc.)"
              },
              "label": {
                "type": "string",
                "description": "The actual content of the note"
              }
            }
          },
          "description": "Note fields"
        },
        "numAvailable": {
          "type": "integer",
          "description": "Number of items available"
        },
        "placeOfPublication": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prefLabel": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Best title(s)"
        },
        "roles:ROLE": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Contributor literals by ROLE"
        },
        "startYear": {
          "type": "integer",
          "description": "Beggining year of coverage"
        },
        "subject": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "suppressed": {
          "type": "boolean",
          "description": "Indicates whether or not resource should be suppressed from view"
        },
        "title": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Title(s)"
        },
        "titleDisplay": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Display title(s)"
        },
        "type": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "nypl:Item",
              "nypl:Collection"
            ]
          }
        },
        "uri": {
          "type": "string",
          "description": "Internal identifier for resource"
        }
      }
    },
    "EntityStub": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        },
        "@id": {
          "type": "string"
        },
        "prefLabel": {
          "type": "string",
          "description": "Friendly label for this entity"
        }
      }
    },
    "Item": {
      "type": "object",
      "properties": {
        "@id": {
          "type": "string"
        },
        "accessMessage": {
          "type": "array",
          "description": "OPAC Access Message",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "deliveryLocation": {
          "type": "array",
          "description": "Delivery locations",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "eddRequestable": {
          "description": "Boolean indicating whether or not item is available for Electronic Document Delivery.",
          "type": "boolean"
        },
        "holdingLocation": {
          "type": "array",
          "description": "Delivery locations",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "idBarcode": {
          "type": "string"
        },
        "identifier": {
          "type": "array",
          "description": "Array of identifiers (e.g. urn:barcode:33433058873765)",
          "items": {
            "type": "string"
          }
        },
        "owner": {
          "type": "array",
          "description": "Owning institution",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "physRequestable": {
          "type": "boolean",
          "description": "Indiates whether an item is available for a physical hold request"
        },
        "requestable": {
          "type": "array",
          "description": "Boolean indicating whether or not a hold request may be placed on this item based on its status, location, and other concerns.",
          "items": {
            "type": "boolean"
          }
        },
        "shelfMark": {
          "type": "array",
          "description": "Callnumber(s)",
          "items": {
            "type": "string"
          }
        },
        "specRequestable": {
          "type": "boolean",
          "description": "Indicates if an item is requestable through the Aeon interface"
        },
        "status": {
          "type": "array",
          "description": "Availability status",
          "items": {
            "$ref": "#/definitions/EntityStub"
          }
        },
        "uri": {
          "type": "string",
          "description": "Internal identifier for resource"
        }
      }
    },
    "Aggregation": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string",
          "enum": [
            "nypl:Aggregation"
          ]
        },
        "@id": {
          "type": "string",
          "description": "Identifies field being aggregated"
        },
        "field": {
          "type": "string",
          "description": "Identifies field being aggregated"
        },
        "values": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AggregationValue"
          }
        }
      }
    },
    "AggregationValue": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "description": "term aggregated"
        },
        "count": {
          "type": "integer",
          "description": "number of records matching term"
        }
      }
    },
    "ResourceError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "fields": {
          "type": "string"
        }
      }
    }
  }
}