swagger: "2.0"
host: api.aucklandmuseum.com
info:
  contact:
    name: Auckland Museum API Team
    url: http://www.aucklandmuseum.com
  description: |
    This is technical documentation for the Auckland Museum API
  license:
    name: Auckland Museum licence
    url: http://www.aucklandmuseum.com
  termsOfService: http://api.aucklandmuseum.com/terms/
  title: Auckland Museum API
  version: 2.0.0
  x-apisguru-categories:
    - open_data
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://twitter.com/aucklandmuseum/profile_image?size=original
  x-origin:
    - format: swagger
      url: http://api.aucklandmuseum.com/apidoc
      version: "2.0"
  x-providerName: aucklandmuseum.com
tags:
  - description: media - images and documents
    name: media
  - description: information about subjects
    name: subject
  - description: search for interesting data
    name: search
  - description: sparql queries
    name: sparql
paths:
  "/id/media/{path}":
    get:
      description: |
        Gets `media` at a given path
      operationId: get media
      parameters:
        - description: |
            The media `identifier`
          in: path
          name: path
          required: true
          type: string
        - description: |
            The desired media `rendering`

            Possible values:
            * `original.jpg`
            * `original.pdf`
            * `thumbnail.jpg` (fixed with 70px)
            * `standard.jpg` (fixed width 440px and height 440px)
            * `preview.jpg` (fixed height 100px)
          in: query
          name: rendering
          required: false
          type: string
      produces:
        - image/jpeg
        - application/pdf
      responses:
        "200":
          description: |
            `media` found
        "404":
          description: |
            `media` not found
      summary: Retrieve media associated with Collections and Cenotaph subjects in Auckland Museum
      tags:
        - media
  "/id/{identifier}":
    get:
      description: |
        Gets information about a `subject` identified by the `identifier`.

        The response format depends upon the `Accept` header.
          - `text/html` - the default response type. Returned data can be easily viewed in any modern Internet Browser
          - `application/ld+json` - the response will be in [JSON-LD](http://json-ld.org/)
          - `application/json` - the response will be a simple JSON Object with keys (predicates) and values (objects).
      operationId: get subject
      parameters:
        - description: |
            The identifier path of the `subject` you're looking for
          in: path
          name: identifier
          required: true
          type: string
      produces:
        - text/html
        - application/ld+json
        - application/json
      responses:
        "200":
          description: |
            `subject` found
        "404":
          description: |
            `subject` not found
      summary: Explore details about a given subject node
      tags:
        - subject
  "/search/{index}/{operation}":
    get:
      description: |
        Use this endpoint to perform simple search queries for finding information and subjects you may be interested in

        Searches performed via this endpoint run against an [Elastic](www.elastic.co) server. This endpoint mirrors the Elastic search API documented [here](https://www.elastic.co/guide/en/elasticsearch/reference/1.5/search-search.html)

        Use the
          - `collectionsonline` index to perform searches over other all
        Collections data
          - `cenotaph` index to perform searches over Cenotaph data
      operationId: get search
      parameters:
        - description: |
            search index name
            Possible values:
            * `collectionsonline`
            * `cenotaph`
          in: path
          name: index
          required: true
          type: string
        - description: One of the supported elasticsearch operations like `_search` or `_suggest`
          in: path
          name: operation
          required: true
          type: string
        - description: One of the supported elasticsearch query parameter values for key `q`
          in: query
          name: q
          required: false
          type: string
      responses:
        "200":
          description: search results found
        "400":
          description: bad request
        "404":
          description: not found
      summary: Perform simple search queries over Auckland Museum Collections and Cenotaph data
      tags:
        - search
    post:
      consumes:
        - application/json
      description: |
        Searches performed via this endpoint run against an [Elastic](www.elastic.co) server. This endpoint mirrors the Elastic search API documented [here](https://www.elastic.co/guide/en/elasticsearch/reference/1.5/search-search.html)

        Use the
          - `collectionsonline` index to perform searches over other all Collections data
          - `cenotaph` index to perform searches over Cenotaph data
      operationId: post search
      parameters:
        - description: |
            search index name
            Possible values:
            * `collectionsonline`
            * `cenotaph`
          in: path
          name: index
          required: true
          type: string
        - description: One of the supported elasticsearch operations like `_search` or `_suggest`
          in: path
          name: operation
          required: true
          type: string
        - description: body
          in: body
          name: body
          required: false
          schema:
            format: application/json
            type: object
      responses:
        "200":
          description: search results found
        "400":
          description: bad request
        "404":
          description: not found
      summary: Perform complex search queries over Auckland Museum Collections and Cenotaph data
      tags:
        - search
  /sparql:
    get:
      description: |
        You can execute your [SPARQL](http://www.w3.org/TR/rdf-sparql-query/) queries against this endpoint.

        The sparql query should be provided as the value of the request parameter `query`.
        Set the `Accept` header to `application/sparql-results+xml` to get results in XML. Set it to `application/sparql-results+json` to get results in JSON. 

        **Note:** This endpoints supports [JSON-P](http://json-p.org/). In order to get a JSON-P response, set the query parameter `callback` to your preferred callback function name. The default function name is `callback()`. When using JSON-P, there is no need to set the `Accept` header because the response will always be in `application/javascript`.
      operationId: get sparql
      parameters:
        - description: sparql query
          in: query
          name: query
          required: true
          type: string
        - default: callback
          description: The [JSON-P](http://json-p.org/) callback parameter
          in: query
          name: callback
          required: false
          type: string
        - default: true
          description: Whether to get inferred results in the response
          in: query
          name: infer
          required: false
          type: boolean
      produces:
        - application/sparql-results+json
        - application/sparql-results+xml
        - application/javascript
      responses:
        "200":
          description: success
          schema:
            title: json
            type: object
      summary: Auckland Museum SPARQL endpoint
      tags:
        - sparql
    post:
      consumes:
        - application/x-www-form-urlencoded
      description: |
        You can execute your [SPARQL](http://www.w3.org/TR/rdf-sparql-query/) queries against this endpoint.
        The sparql query should be provided as the value of the request parameter `query`.
        Set the `Accept` header to `application/sparql-results+xml` to get results in XML. Set it to `application/sparql-results+json` to get results in JSON. 
      operationId: post sparql
      parameters:
        - description: sparql query
          in: formData
          name: query
          required: true
          type: string
        - default: true
          description: Whether to get inferred results in the response
          in: formData
          name: infer
          required: false
          type: boolean
      produces:
        - application/sparql-results+json
        - application/sparql-results+xml
      responses:
        "200":
          description: success
      summary: Auckland Museum SPARQL endpoint
      tags:
        - sparql
