@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Auckland Museum API
@base https://api.aucklandmuseum.com
@version 2.0.0
@endpoints 6
@toc search(2), id(2), sparql(2)

@group search
@endpoint GET /search/{index}/{operation}
@desc Perform simple search queries over Auckland Museum Collections and Cenotaph data
@required {index: any # search index name Possible values: * `collectionsonline` * `cenotaph`, operation: any # One of the supported elasticsearch operations like `_search` or `_suggest`}
@optional {q: any # One of the supported elasticsearch query parameter values for key `q`}
@returns(200) search results found
@errors {400: bad request, 404: not found}

@endpoint POST /search/{index}/{operation}
@desc Perform complex search queries over Auckland Museum Collections and Cenotaph data
@required {index: any # search index name Possible values: * `collectionsonline` * `cenotaph`, operation: any # One of the supported elasticsearch operations like `_search` or `_suggest`}
@optional {body: map # body}
@returns(200) search results found
@errors {400: bad request, 404: not found}

@endgroup

@group id
@endpoint GET /id/{identifier}
@desc Explore details about a given subject node
@required {identifier: any # The identifier path of the `subject` you're looking for}
@returns(200) `subject` found
@errors {404: `subject` not found}

@endpoint GET /id/media/{path}
@desc Retrieve media associated with Collections and Cenotaph subjects in Auckland Museum
@required {path: any # The media `identifier`}
@optional {rendering: any # 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)}
@returns(200) `media` found
@errors {404: `media` not found}

@endgroup

@group sparql
@endpoint GET /sparql
@desc Auckland Museum SPARQL endpoint
@required {query: any # sparql query}
@optional {callback: any # The [JSON-P](http://json-p.org/) callback parameter, infer: any # Whether to get inferred results in the response}
@returns(200) success

@endpoint POST /sparql
@desc Auckland Museum SPARQL endpoint
@required {query: any # sparql query}
@optional {infer: any # Whether to get inferred results in the response}
@returns(200) success

@endgroup

@end