From 46d28c119ad376b3c13884ed3c094bf5d695a73c Mon Sep 17 00:00:00 2001 From: Jari Voutilainen Date: Thu, 23 Nov 2017 11:07:49 +0200 Subject: [PATCH] Add swagger.yaml --- doc/Avoindata-rest-api_1.0.0_swagger.yaml | 676 ++++++++++++++++++++++ 1 file changed, 676 insertions(+) create mode 100644 doc/Avoindata-rest-api_1.0.0_swagger.yaml diff --git a/doc/Avoindata-rest-api_1.0.0_swagger.yaml b/doc/Avoindata-rest-api_1.0.0_swagger.yaml new file mode 100644 index 0000000000..6ef37dad14 --- /dev/null +++ b/doc/Avoindata-rest-api_1.0.0_swagger.yaml @@ -0,0 +1,676 @@ +swagger: '2.0' +info: + description: | + Simple API to manage open data sets in avoindata.fi + + # Important note + This is not a traditional rest API in the strict sense. **It does not use PUT or DELETE http methods**. Instead, it does everything with GET or POST methods. This means that the color coding in the (swagger) documentation is misleading. + + # Open and limited access functions + + Functions which can be used **without authorization are grouped under _consumers_**. + Some API functions **require authorization (grouped under _admins_)**. With these methods you will need API key provided by CKAN system. + + **In every API call you need to provide APInf platform specific API-key**. You can get that by creating account. After logging in, your API key is visible in every API profile page (top right corner). +
+ ![Imgur](https://i.imgur.com/bEGmr2s.png) +
+ + # A few simple examples + + **Simple example to list datasets** is: + + ``curl -X GET "https://kokeilu.apinf.io:3002/avoindatabeta/package_list" -H "X-API-Key: YOUR APINF API KEY"`` + + which returns JSON formatted list of datasets. + + **Simple example to view details of one dataset** is: + + ``curl -X GET "https://kokeilu.apinf.io:3002/avoindatabeta/package_show?id=digiroad" -H "X-API-Key: YOUR APINF API KEY"`` + + which returns JSON formatted detailed infomation about identified dataset. + + + # Authentication and API keys + + There's two kind of keys: + - **X-API-Key**. APInf Platform API key used in analytics. This required in all API calls. You can get that by creating account. After logging in, your API key is visible in every API profile page (right top corner). + - **Authorization**. To authorize user to do admin operations in CKAN system. + + Some API functions require authorization (grouped under _admins_). The API uses the same authorization functions and configuration as the web interface, so if a user is authorized to do something in the web interface they’ll be authorized to do it via the API as well. + + When calling an API function that requires authorization, you must authenticate yourself by providing your API key with your HTTP request. To find your API key, login to the CKAN site using its web interface and visit your user profile page. In SwaggerUI, you need to input CKAN authorization API-key to _Authorization_ value field. Open authentication dialog by clicking _Authorize_ button. + + # Datamodels + + All datamodels used are defined in separate service. LINKS HERE! + + version: 1.0.0 + title: Avoindata.fi API + # put the contact info for your development or API team + contact: + email: you@your-company.com + + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html +schemes: + - https +securityDefinitions: +# key: +# type: apiKey +# in: header +# name: X-API-Key + ckanapikey: + type: apiKey + name: Authorization + in: header + +# tags are used for organizing operations +tags: +- name: consumers + description: Operations available to regular consumers +- name: admins + description: Secured Admin-only calls + +paths: + + /package_list: + get: + ## security: + ## - key: [] + tags: + - consumers + summary: List all datasets within given limit + operationId: listInventory + description: | + List or search all datasets + produces: + - application/json + parameters: + - in: query + name: offset + description: when limit is given, the offset to start returning packages from + required: false + type: integer + - in: query + name: limit + description: if given, the list of datasets will be broken into pages of at most limit datasets per page and only one page will be returned at a time (optional) + type: integer + format: int32 + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/InventoryItem' + 400: + description: bad input parameter + + /package_search: + get: + ## security: + ## - key: [] + tags: + - consumers + summary: Search among all datasets + operationId: searchInventory + description: | + List or search all datasets + produces: + - application/json + parameters: + - in: query + name: q + description: the solr query. For example ``name:pdf-testi`` + required: false + type: string + default: "*:*" + - in: query + name: fq + type: string + description: | + any filter queries to apply. Note: +site_id:{ckan_site_id} is added to this string prior to the query being executed. + + - in: query + name: sort + description: | + sorting of the search results. Optional. **Default: 'relevance asc, metadata_modified desc'**. As per the solr documentation, this is a comma-separated string of field names and sort-orderings. + required: false + type: string + default: "relevance asc, metadata_modified desc" + - in: query + name: rows + description: the number of matching rows to return. There is a hard limit of 1000 datasets per query. + required: false + type: integer + - in: query + name: start + type: integer + description: the offset in the complete result for where the set of returned datasets should begin. + - in: query + name: include_drafts + type: boolean + default: false + description: if True, draft datasets will be included in the results. A user will only be returned their own draft datasets, and a sysadmin will be returned all draft datasets. Optional, the default is False. + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/InventoryItem' + 400: + description: bad input parameter + 409: + description: Conflict (can result e.g. from incorrectly formatted solr query) + + + /package_show: + get: + ##security: + ## - key: [] + tags: + - consumers + summary: Get details of one package + operationId: showInventory + description: | + List or search all datasets + produces: + - application/json + parameters: + - in: query + name: id + description: the id or name of the dataset + required: true + type: string + - in: query + name: include_tracking + description: | + add tracking information to dataset and resources (default: False) + type: boolean + default: false + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/InventoryItem' + 400: + description: bad input parameter + + /organization_list: + get: + ##security: + ## - key: [] + tags: + - consumers + summary: List all groups within given parameters + operationId: listOrgs + description: | + List or search all datasets + produces: + - application/json + parameters: + - in: query + name: sort + description: | + sorting of the search results. Optional. Default: “name asc” string of field name and sort-order. The allowed fields are ‘name’, ‘package_count’ and ‘title’ + required: false + default: "name asc" + type: string + - in: query + name: limit + description: | + if given, the list of organizations will be broken into pages of at most limit organizations per page and only one page will be returned at a time (optional) + type: integer + format: int32 + - in: query + name: offset + description: | + when limit is given, the offset to start returning organizations from + type: integer + format: int32 + required: false + - in: query + name: organizations + type: string + description: | + a list of names of the groups to return, if given only groups whose names are in this list will be returned (optional) + required: false + - in: query + type: boolean + name: all_fields + description: | + return group dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the packages property for each group is deprecated, but there is a count of the packages in the package_count property. (optional, default: False) + required: false + - in: query + name: include_dataset_count + type: boolean + default: true + description: | + if all_fields, include the full package_count (optional, default: True) + - in: query + name: include_extras + type: boolean + description: | + if all_fields, include the organization extra fields (optional, default: False) + default: false + - in: query + name: include_tags + type: boolean + description: | + if all_fields, include the organization tags (optional, default: False) + default: false + - in: query + name: include_groups + type: boolean + description: | + if all_fields, include the organizations the organizations are in (optional, default: False) + default: false + - in: query + name: include_users + type: boolean + description: | + if all_fields, include the organization users (optional, default: False). + default: false + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/InventoryItem' + 400: + description: bad input parameter + + /package_create: + post: + security: + - ckanapikey: [] + tags: + - admins + summary: Create a new dataset (package) + operationId: addDataset + description: Creates a new dataset (package) to the system. You must be authorized to create new datasets. If you specify any groups for the new dataset, you must also be authorized to edit these groups. + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: inventoryItem + description: Inventory item to add + schema: + $ref: '#/definitions/dataset_package_create' + responses: + 201: + description: item created + 400: + description: invalid input, object invalid + 409: + description: an existing item already exists + /package_update: + post: + security: + - ckanapikey: [] + tags: + - admins + summary: Update a dataset (package). + operationId: updateDataset + description: Update a dataset (package). You must be authorized to edit the dataset and the groups that it belongs to. + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: inventoryItem + description: Inventory item to add + schema: + $ref: '#/definitions/dataset_package_update' + responses: + 200: + description: OK, dataset updated. + 400: + description: Invalid input, object invalid. + 404: + description: Object not found for update. + /package_delete: + post: + security: + - ckanapikey: [] + tags: + - admins + summary: Delete a dataset (package) + operationId: deleteDataset + description: This makes the dataset disappear from all web & API views, apart from the trash. + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: id + description: id (string) – the id or name of the dataset to delete. + schema: + $ref: '#/definitions/delete' + responses: + 200: + description: OK, dataset deleted. + 404: + description: =bject not found for deletion. + /organization_create: + post: + security: + - ckanapikey: [] + tags: + - admins + summary: Create a new organization. + operationId: addOrg + description: Create a new organization. You must be authorized to create organizations. + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: inventoryItem + description: Inventory item to add + schema: + $ref: '#/definitions/dataset_organization_create' + responses: + 201: + description: Organization created + 400: + description: Invalid input, object invalid + 409: + description: An existing item already exists + /organization_update: + post: + security: + - ckanapikey: [] + tags: + - admins + summary: Update a organization. + operationId: updateOrg + description: Update a organization. You must be authorized to edit the organization. + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: inventoryItem + description: Inventory item to add + schema: + $ref: '#/definitions/dataset_organization_update' + responses: + 200: + description: OK, updated. + 400: + description: Invalid input, object invalid + 404: + description: Organization not found for update. + /organization_delete: + post: + security: + - ckanapikey: [] + tags: + - admins + summary: Delete an organization. + operationId: deleteOrg + description: Delete an organization. You must be authorized to delete the organization. + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: id + description: id (string) – the id or name of the organization to delete + schema: + $ref: '#/definitions/delete' + responses: + 200: + description: OK, organization deleted. + 400: + description: Invalid input, object invalid. + 404: + description: Organization not found for deletion. + + /user_list: + get: + security: + - ckanapikey: [] + tags: + - admins + summary: List users + operationId: listUsers + description: Return a list of the site’s user accounts. + consumes: + - application/json + produces: + - application/json + parameters: + - in: query + name: q + required: false + default: "*" + description: Restrict the users returned to those whose names contain a string. Optional. + type: string + - in: query + name: order_by + required: false + default: "*" + description: Which field to sort the list by. Can be any user field or edits (i.e. number_of_edits). Optional. + type: string + - in: query + name: all_fields + required: false + default: True + description: Return full user dictionaries instead of just names. Optional. + type: boolean + + responses: + 200: + description: Returns a list of users. if there is no match, empty list is returned. + examples: + application/json: + { + "help": "https://beta.avoindata.fi/data/api/3/action/help_show?name=user_list", + "success": true, + "result": [ + { + "openid": null, + "about": null, + "apikey": "916f7088-5828-4e25-a0da-f5fcad281af2", + "display_name": "makkonenmakkonen", + "name": "etunimi sukunimi", + "created": "2017-10-31T15:05:59.402582", + "email": "esa.merkki@apinf.io", + "sysadmin": false, + "activity_streams_email_notifications": false, + "state": "active", + "number_of_edits": 3, + "fullname": null, + "id": "9d886b53-2f4a-4ed8-8482-bd2cb9d0d5fe", + "number_created_packages": 3 + } + ] + } + + 400: + description: invalid input, object invalid. + 403: + description: Forbidden, authorization key missing. + 409: + description: Item already exists. + + +definitions: + delete: + type: object + + properties: + id: + type: string + example: id-to-delete + description: | + Id to delete + + dataset_package_create: + type: object + required: + - name + - collection_type + - license_id + - owner_org + + properties: + name: + type: string + description: | + the name of the new dataset, must be between 2 and 100 characters long and contain only lowercase alphanumeric characters, - and _, e.g. 'warandpeace' + example: name + collection_type: + type: string + default: "Open Data" + description: | + 'Open Data' or 'Interoperability Tools' values allowed + example: Open Data + license_id: + type: string + example: EUPL + description: | + License + owner_org: + type: string + description: | + Owner; 'yksityishenkilo' value allowed at the moment + example: yksityishenkilo + title_translated: + type: object + description: | + list of localised titles + example: + fi: Aihe suomeksi + de: Thema in Deutsche + notes_translated: + type: object + description: | + list of localised notes + example: + fi: Muistiinpanot suomeksi + de: Notiz in Deutsche + + dataset_package_update: + type: object + required: + - id + - name + - license_id + - collection_type + - owner_org + properties: + id: + type: string + example: example id + description: | + the name or id of the dataset to update + name: + type: string + example: organization + description: name of the package to update + license_id: + type: string + description: id of the licence + example: ididididid + collection_type: + type: string + default: "Open Data" + description: | + 'Open Data' or 'Interoperability Tools' values allowed + example: Open Data + owner_org: + type: string + description: | + Owner; 'yksityishenkilo' value allowed at the moment + example: yksityishenkilo + + dataset_organization_create: + type: object + required: + - name + + properties: + name: + type: string + example: "nameofanorganization" + description: | + Name (string) – the name of the organization, a string between 2 and 100 characters long, containing only lowercase alphanumeric characters, - and _ + description: + type: string + example: great organization + description: | + Description of the organization + id: + type: string + example: ididididid + description: | + ID of the organization + + dataset_organization_update: + type: object + required: + - id + + properties: + name: + type: string + example: "nameofanorganization" + description: | + Name (string) – the name of the organization, a string between 2 and 100 characters long, containing only lowercase alphanumeric characters, - and _ + id: + type: string + example: ididididid + description: | + ID of the organization + + InventoryItem: + type: object + required: + - id + - name + - manufacturer + - releaseDate + properties: + id: + type: string + format: uuid + example: d290f1ee-6c54-4b01-90e6-d701748f0851 + name: + type: string + example: Widget Adapter + releaseDate: + type: string + format: int32 + example: 2016-08-29T09:12:33.001Z + manufacturer: + $ref: '#/definitions/Manufacturer' + Manufacturer: + required: + - name + properties: + name: + type: string + example: ACME Corporation + homePage: + type: string + format: url + example: https://www.acme-corp.com + phone: + type: string + example: 408-867-5309 \ No newline at end of file