swagger: '2.0' info: description: >- The NADA REST API allows depositing data, catalog management and querying and exploring metadata. You can find out more about NADA at [http://nada.ihsn.org](http://nada.ihsn.org). To use the API, you will require the '`API-KEY'`, see the section `Authentication` version: 1.0.0 title: NADA license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' basePath: /index.php/api/ tags: - name: Authentication description: Authentication - name: Data deposit description: API for data deposit - name: Project description: API for data deposit projects - name: Project metadata description: API for data deposit metadata read/write - name: Project resources description: API For project related resources - name: Project citations description: API For project related citations - name: User projects description: Get projects by user - name: Catalog administration description: 'How to import, publish, update studies in the catalog' - name: Metadata description: Query and extract metadata - name: Catalog search description: Search data catalog x-tagGroups: - name: Authentication tags: - Authentication - name: Data Deposit tags: - Project - Project metadata - Project resources - Project citations - User projects - name: Catalog administration tags: - Catalog administration schemes: - http paths: /auth/login: post: tags: - Authentication summary: Login description: Login using email/password. It returns all API keys associated with the user account operationId: AuthLogin consumes: - application/json produces: - application/xml - application/json parameters: - in: "formData" name: "email" required: true - in: "formData" name: "password" required: true responses: '200': description: successful operation schema: $ref: '#/definitions/AuthenticationResponse' security: - ApiKeyAuth: [] /datadeposits: get: tags: - Data deposit - Project summary: List all projects description: Returns a list of all projects operationId: listProject consumes: - application/json - application/xml produces: - application/xml - application/json responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] post: tags: - Data deposit - Project summary: Create new project description: Create new project operationId: addProject consumes: - application/json produces: - application/xml - application/json parameters: - in: "body" name: "body" required: true schema: $ref: "#/definitions/Project" responses: '200': description: successful operation schema: $ref: '#/definitions/ApiResponse' '400': description: Invalid input security: - ApiKeyAuth: [] /datadeposits/{projectId}: put: tags: - Data deposit - Project summary: Update project description: Update project options operationId: putProject consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - in: "body" name: "body" required: true schema: $ref: "#/definitions/Project" responses: '200': description: successful operation schema: $ref: '#/definitions/ApiResponse' '400': description: Bad input security: - ApiKeyAuth: [] get: tags: - Data deposit - Project summary: Get a single project description: Get a single project by project ID operationId: getProjectById produces: - application/xml - application/json parameters: - name: projectId in: path description: ID of project to return required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Project' '400': description: Bad input or validation error '404': description: Project not found security: - ApiKeyAuth: [] delete: tags: - Data deposit - Project summary: Delete project description: Delete a project operationId: deleteProject produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: projectId in: path description: Project id to delete required: true type: integer format: int64 responses: '200': description: successful operation '400': description: Operation failed '404': description: Project not found security: - ApiKeyAuth: [] /datadeposits/{projectId}/access_policy: put: tags: - Data deposit - Project summary: Set access policy description: Update project access policy options operationId: putProjectAccessPolicy consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - in: "body" name: "body" required: true schema: $ref: "#/definitions/ProjectAccessPolicy" responses: '200': description: successful operation schema: $ref: '#/definitions/ApiResponse' '400': description: Bad input security: - ApiKeyAuth: [] get: tags: - Data deposit - Project summary: Get access policy description: Get project access policy info operationId: getProjectAccessPolicy consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/ApiResponse' '400': description: Bad input security: - ApiKeyAuth: [] /datadeposits/{projectId}/submit: put: tags: - Data deposit - Project summary: Submit project description: Submit project for review, this action locks the project for any further changes and triggers and email notification. operationId: putProjectSubmit consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/ApiResponse' '400': description: Bad input security: - ApiKeyAuth: [] /datadeposits/{projectId}/{status}: put: tags: - Data deposit - Project summary: Change project status description: Utility function to be removed. operationId: putProjectStatus consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: status in: path description: Project status code e.g. draft, submitted, processed, closed required: true type: string format: string responses: '200': description: successful operation schema: $ref: '#/definitions/ApiResponse' '400': description: Bad input security: - ApiKeyAuth: [] /datadeposits/user_projects: get: tags: - Data deposit - User projects summary: List projects by current user description: Returns a list of all projects by the current logged in user operationId: listCurrentUserProjects consumes: - application/json - application/xml produces: - application/xml - application/json responses: '200': description: successful operation schema: $ref: '#/definitions/Project' '400': description: Bad request security: - ApiKeyAuth: [] /datadeposits/user_projects/{userId}: get: tags: - Data deposit - User projects summary: List user projects description: Returns a list of all projects by a user operationId: listUserProjects consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - name: userId in: path description: User ID required: true type: integer format: int64 responses: '400': description: Bad request '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] /datadeposits/metadata/{projectId}: get: tags: - Data deposit - Project metadata summary: Get project metadata description: Returns project metadata using the JSON schema format used by the project operationId: projectMetadata consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 responses: '400': description: Bad request '200': description: successful operation schema: $ref: '#/definitions/MetadataSchema' security: - ApiKeyAuth: [] post: tags: - Data deposit - Project metadata summary: Update project metadata description: Update project metadata using the JSON schemas operationId: projectMetadataUpdate consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - in: "body" name: "body" required: true schema: $ref: "#/definitions/MetadataSchema" responses: '400': description: Bad request '200': description: successful operation schema: $ref: '#/definitions/MetadataSchema' security: - ApiKeyAuth: [] '/datadeposits/{projectId}/resources': get: tags: - Data deposit - Project resources summary: List project resources description: List all data files and other resources attached to the project operationId: getProjectResources produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Resource' '400': description: Invalid ID supplied '404': description: Project not found security: - ApiKeyAuth: [] post: tags: - Data deposit - Project resources summary: Upload a resource file description: Upload project resources operationId: UploadProjectResource consumes: - multipart/form-data produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: resource_type in: formData required: false description: Resource type type: string - name: title in: formData required: false description: Resource title type: string - name: description in: formData required: false description: Resource description type: string - name: file in: formData required: true description: Upload a file type: file responses: '400': description: Bad input '200': description: Success security: - ApiKeyAuth: [] /datadeposits/{projectId}/resources/{resourceId}: get: tags: - Data deposit - Project resources summary: Find a resource by ID description: Returns a single resource for the project operationId: getProjectResource produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: resourceId in: path description: Resource ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Project' '400': description: Invalid ID supplied '404': description: Resource not found security: - ApiKeyAuth: [] put: tags: - Data deposit - Project resources summary: Update project resource description: Update resource description. operationId: UpdateProjectResource consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: resourceId in: path required: true description: Resource ID type: string - in: "body" name: "body" required: false schema: $ref: "#/definitions/Resource" responses: '200': description: successful operation schema: $ref: '#/definitions/Resource' '400': description: Bad input security: - ApiKeyAuth: [] delete: tags: - Data deposit - Project resources summary: Delete a resource description: 'Delete a projct resource' operationId: deleteProjectResource produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: resourceId in: path description: Resource ID to delete required: true type: integer format: int64 responses: '400': description: Bad input '200': description: Success security: - ApiKeyAuth: [] '/datadeposits/{projectId}/citations': get: tags: - Data deposit - Project citations summary: List citations description: List all citations attached to the project operationId: getProjectCitations produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Citation' '400': description: Bad input security: - ApiKeyAuth: [] post: tags: - Data deposit - Project citations summary: Add citation description: Add new citation operationId: AddProjectCitation consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - in: body name: body description: Citation JSON in request body schema: $ref: '#/definitions/Citation' responses: '400': description: Bad input '200': description: successful operation schema: $ref: '#/definitions/Citation' security: - ApiKeyAuth: [] /datadeposits/{projectId}/citations/{citationId}: get: tags: - Data deposit - Project citations summary: Find citation by ID description: Returns a single citation for the project operationId: getProjectCitation produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: citationId in: path description: Citation ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Citation' '400': description: Invalid ID supplied '404': description: Citation not found security: - ApiKeyAuth: [] put: tags: - Data deposit - Project citations summary: Update citation description: Update citation operationId: UpdateProjectCitation consumes: - application/json produces: - application/xml - application/json parameters: - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: citationId in: path required: true description: Citation ID type: string - in: "body" name: "body" required: false schema: $ref: "#/definitions/Citation" responses: '200': description: successful operation schema: $ref: '#/definitions/Citation' '400': description: Bad input security: - ApiKeyAuth: [] delete: tags: - Data deposit - Project citations summary: Delete citation description: 'Delete a projct citation' operationId: deleteProjectCitation produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: projectId in: path description: Project ID required: true type: integer format: int64 - name: citationId in: path description: Citation ID to delete required: true type: integer format: int64 responses: '400': description: Bad input '200': description: Success security: - ApiKeyAuth: [] /studies: get: tags: - Catalog administration - Studies summary: List all studies description: Returns a list of all studies operationId: listStudies consumes: - application/json - application/xml produces: - application/xml - application/json responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] /studies/import: post: tags: - Catalog administration - Studies summary: Import a study description: Import a study from DDI, ISO19139 XML file operationId: importStudy consumes: - application/json - application/xml produces: - application/xml - application/json responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] /studies/{studyId}: get: tags: - Catalog administration - Studies summary: Get a single study description: Retrieve a single study by ID operationId: listSingleStudy consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: studyId in: path description: Study ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] delete: tags: - Catalog administration - Studies summary: Delete study description: 'Delete a study' operationId: deleteStudy produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: studyId in: path description: Project ID required: true type: integer format: int64 responses: '400': description: Bad input '200': description: Success security: - ApiKeyAuth: [] /studies/{studyId}/resources: get: tags: - Catalog administration - Studies summary: Get study resources description: Get all study related resources operationId: listStudyResources consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: studyId in: path description: Study ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] post: tags: - Catalog administration - Studies summary: Add study resource description: Create a new resource operationId: addStudyResources consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: studyId in: path description: Study ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] /studies/{studyId}/resources/{resourceId}: get: tags: - Catalog administration - Studies summary: Get a single resource description: Get a single study resources operationId: getStudySingleResource consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - name: api_key in: header required: false type: string - name: studyId in: path description: Study ID required: true type: integer format: int64 - name: resourceId in: path description: Resource ID required: true type: integer format: int64 responses: '200': description: successful operation schema: $ref: '#/definitions/Project' security: - ApiKeyAuth: [] ############################################################### securityDefinitions: ApiKeyAuth: type: apiKey name: X-API-KEY in: header definitions: Project: type: object properties: id: type: integer format: int64 readOnly: true project_type: type: string enum: - survey - geospatial title: type: string description: type: string shortname: type: string collaborators: type: array format: email items: type: string example: - user@example.com - user2@example.com status: type: string readOnly: true description: Project status codes * `draft` - Draft mode * `submitted` - Project is submitted and locked for user to make any further changes * `processed` - Project accepted and is being processed * `closed` - Processing completed and project is completed * `published` - Project published to one or more catalogs * `cancelled` - Project was cancelled enum: - draft - submitted - processed - closed - cancelled - published created: type: string format: date-time readOnly: true changed: type: string format: date-time readOnly: true xml: name: Project ProjectAccessPolicy: type: object properties: id: type: integer format: int64 readOnly: true access_policy: type: string description: Select the access policy suitable for your data. * `direct` - Direct access * `public` - Public access * `licensed` - Licensed access, require users to register and submit request for access * `enclave` - Data Enclave * `remote` - Date available from remote repository * `other` - Other enum: - open - direct - public - licensed - enclave - remote - other to_catalog: type: string description: Select catalog for publishing the data * `internal` - Internal catalog * `external` -External public catalog enum: - internal - external is_embargoed: type: boolean description: Is the data embargoed? enum: - 0 [No] - 1 [Yes] embargoed_notes: type: string description: indicate the terms of the embargo e.g. time period and any other special instructions. disclosure_risk: type: string description: Safeguarding the identity and privacy of respondents that have provided the data is important. If the data files you are depositing contain any identifying variables (e.g., names, official ID numbers, precise GIS coordinates, etc) or any variables deemed otherwise sensitive in your study setting (e.g., ethnicity, tribe, religion, etc) please list these below so that access to these can be suppressed. library_notes: type: string description: Notes for the deposit reviewers cc: type: string description: Enter the email addresses seperated by semicolon(;) of additional people you would like to receive a summary copy of your submission. created: type: string format: date-time readOnly: true changed: type: string format: date-time readOnly: true xml: name: MetadataSchema MetadataSchema: type: object properties: id: type: integer format: int64 readOnly: true project_type: type: string enum: - survey - geospatial other_fields: type: object description: Schema for one of the supported types xml: name: MetadataSchema AuthenticationResponse: type: object properties: id: type: integer format: int64 readOnly: true user_id: type: int username: type: string api-keys: type: object xml: name: AuthenticationResponse Resource: type: object properties: id: type: integer format: int64 readOnly: true pid: type: integer format: int64 description: Project ID resource_type: type: string enum: - microdata - questionnaire - report - table - other title: type: string description: type: string filename: type: string created: type: string format: date-time changed: type: string format: date-time xml: name: Resource Citation: type: object properties: id: type: integer format: int64 readOnly: true pid: type: integer format: int64 description: Project ID citation_type: type: string enum: - book - journal - article - website - other title: type: string subtitle: type: string authors: type: array items: type: object properties: fname: type: string lname: type: string volume: type: string issue: type: string idnumber: type: string edition: type: string pub_place: type: string publisher: type: string pub_medium: type: string url: type: string page_from: type: integer page_to: type: integer pub_date: type: string example: Full or partial date .e.g Month/Year or Year abstract: type: string keywords: type: string doi: type: string country: type: string created: type: string format: date-time changed: type: string format: date-time required: - pid - title xml: name: Citation ApiResponse: type: object properties: code: type: integer format: int32 type: type: string message: type: string externalDocs: description: Find out more about Swagger url: 'http://swagger.io'