dati_mit_gov_it_yaml

swagger: '2.0'
info:
  description: |
    Simple API to manage open data sets in data.mit.gov.it

    # 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).
    <center>
    ![Imgur](https://i.imgur.com/bEGmr2s.png)
    </center>

    # A few simple examples

    **Simple example to list datasets** is:

    ``curl -X GET "https://mit.gov.it/catalog/api/3/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://mit.gov.it/catalog/api/3/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. This key can be obtained by signing up to https://beta.avoindata.fi.

    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: 3
  title:  dati.mit.gov.it 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
      - keywords
      - title_translated
      - notes_translated
      - maintainer
      - maintainer_email

    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
      keywords:
        type: object
        description: |
          Localised keywords
        example:
          fi: ["eka","toka","kolmas"]
      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
      maintainer:
        type: string
        description: |
          Maintainer of this data
        example: Jarkko Pöntiö
      maintainer_email:
        type: string
        description: |
          Maintainer email
        example: jarkko.pontio@somedomainhere.com

  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 _
      id:
        type: string
        example: ididididid
        description: |
          ID of the organization (optional)
      title:
        type: string
        example: title
        description: |
          the title of the organization (optional)

      description:
        type: string
        example: great organization
        description: |
          Description of the organization

      image_url:
        type: string
        example: http://image.url.com/exxaample.gif
        description: |
          the URL to an image to be displayed on the organization’s page (optional)

      state:
        type: string
        example: active
        description: |
          the current state of the organization, e.g. 'active' or 'deleted', only active organizations show up in search results and other lists of organizations, this parameter will be ignored if you are not authorized to change the state of the organization (optional, default: 'active')

      approval_status:
        type: string
        example: status description
        description: |
          (string) – (optional)

      extras:
        type: object
        example: [{"value": ["value1"], "key": ["key1"], "active":["false"]}]
        description: |
          (list of dataset extra dictionaries) – the organization’s extras (optional), extras are arbitrary (key: value) metadata items that can be added to organizations, each extra dictionary should have keys 'key' (a string), 'value' (a string), and optionally 'deleted'

      packages:
        type: object
        example: [{"id": "8de6e388-20c1-dddd-df3d-c445f447f1cg", "title":"title"}]
        description: |
          (list of dictionaries) – the datasets (packages) that belong to the organization, a list of dictionaries each with keys 'name' (string, the id or name of the dataset) and optionally 'title' (string, the title of the dataset)

      users:
        type: object
        example: [{"name":"mikko", "capacity": "capacity manager"}, {"name": "suusanna"}]
        description: |
          (list of dictionaries) – the datasets (packages) that belong to the organization, a list of dictionaries each with keys 'name' (string, the id or name of the dataset) and optionally 'title' (string, the title of the dataset)

  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