@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api OpenTrials API
@version 0.0.1
@endpoints 17
@toc search(3), trials(3), publications(1), conditions(1), organisations(1), persons(1), interventions(1), sources(1), fda_applications(2), documents(2), document_categories(1)

@group search
@endpoint GET /search
@desc Returns trials based on a search query. By default, it'll search in all of a trial's attributes.
@optional {q: any # The search query (follows the [ElasticSearch Query String](https://www.elastic.co/guide/en/elasticsearch/reference/2.3/query-dsl-query-string-query.html#query-string-syntax) syntax), page: any # The page number, per_page: any # Number of items per page}
@returns(200) Success

@endpoint GET /search/autocomplete/{in}
@desc Autocomplete search feature for supported database entities (`location`). It has the same options as a regular `search` operation, with an extra **required** `in` parameter indicating the entity type to search.
@required {in: any # The entity to search for}
@optional {q: any # The search query, page: any # The page number, per_page: any # Number of items per page}
@returns(200) Success

@endpoint GET /search/fda_documents
@desc Search the FDA documents
@optional {q: any # The search query (follows the [ElasticSearch Query String](https://www.elastic.co/guide/en/elasticsearch/reference/2.3/query-dsl-query-string-query.html#query-string-syntax) syntax), text: any # Search query on the documents file's text (follows the [ElasticSearch Simple Query String](https://www.elastic.co/guide/en/elasticsearch/reference/2.3/query-dsl-simple-query-string-query.html#_simple_query_string_syntax) syntax), page: any # The page number, per_page: any # Number of items per page}
@returns(200) Success

@endgroup

@group trials
@endpoint GET /trials/{id}
@desc Returns a trial's details and related entities (e.g. `conditions`).
@required {id: any # ID of the trial}
@returns(200) Success
@errors {404: Trial not found}

@endgroup

@group publications
@endpoint GET /publications/{id}
@desc Returns publication details
@required {id: any # ID of the publication}
@returns(200) Success
@errors {404: Publication not found}

@endgroup

@group conditions
@endpoint GET /conditions/{id}
@desc Returns condition details
@required {id: any # ID of the condition}
@returns(200) Success
@errors {404: Condition not found}

@endgroup

@group organisations
@endpoint GET /organisations/{id}
@desc Returns organisation details
@required {id: any # ID of the organisation}
@returns(200) Success
@errors {404: Organisation not found}

@endgroup

@group trials
@endpoint GET /trials/{id}/records
@desc Returns a trial's raw records from its sources
@required {id: any # ID of the trial}
@returns(200) Success
@errors {404: Trial not found}

@endpoint GET /trials/{trialId}/records/{id}
@desc Returns a trial's raw record from its sources
@required {trialId: any # ID of the trial, id: any # ID of the trial's record}
@returns(200) Success
@errors {404: Trial not found}

@endgroup

@group persons
@endpoint GET /persons/{id}
@desc Returns person details
@required {id: any # ID of the person}
@returns(200) Success
@errors {404: Person not found}

@endgroup

@group interventions
@endpoint GET /interventions/{id}
@desc Returns intervention details
@required {id: any # ID of the intervention}
@returns(200) Success
@errors {404: Intervention not found}

@endgroup

@group sources
@endpoint GET /sources
@desc Returns list of sources
@returns(200) Success

@endgroup

@group fda_applications
@endpoint GET /fda_applications
@desc Returns FDA applications
@optional {page: any # The page number, per_page: any # Number of items per page}
@returns(200) Success

@endpoint GET /fda_applications/{id}
@desc Returns an FDA application details
@required {id: any # ID of the FDA application}
@returns(200) Success
@errors {404: FDA application not found}

@endgroup

@group documents
@endpoint GET /documents
@desc Returns documents
@optional {page: any # The page number, per_page: any # Number of items per page}
@returns(200) Success

@endpoint GET /documents/{id}
@desc Returns details of a document
@required {id: any # ID of the document}
@returns(200) Success
@errors {404: Document not found}

@endgroup

@group document_categories
@endpoint GET /document_categories
@desc Returns document categories
@returns(200) Success

@endgroup

@end