#type: collection
get:
  is: [ searchable: { searchFields: "name, desc" }, embeddable: { embedFields: "user,source,topics,synapses,mappings,contributors,collaborators" }, orderable, pageable ]
  securedBy: [ null, token, oauth_2_0 ]
  queryParameters:
    user_id:
      description: |
        Pass a user_id to only return maps created by that user. For example, `/api/v2/maps?user_id=1` would return maps created by the Metamaps user with id 1.
      required: false
      type: number
  responses:
    200:
      body:
        application/json:
          example: !include ../examples/maps.json
post:
  body:
    application/json:
      properties:
        name:
          description: name
        desc:
          description: description
        permission:
          description: commons, public, or private
        source_id:
          description: the id of the map this map is a fork of
        screenshot:
          description: url to a screenshot of the map
        contributor_ids:
          description: the ids of people who have contributed to the map
        collaborator_ids:
          description: the ids of people who have edit access to the map
  responses:
    201:
      body:
        application/json:
          example: !include ../examples/map.json
/{id}:
  #type: item
  get:
    is: [ embeddable: { embedFields: "user,source,topics,synapses,mappings,contributors,collaborators" } ]
    securedBy: [ null, token, oauth_2_0 ]
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/map.json
  put:
    body:
      application/json:
        properties:
          name:
            description: name
            required: false
          desc:
            description: description
            required: false
          permission:
            description: commons, public, or private
            required: false
          screenshot:
            description: url to a screenshot of the map
            required: false
          source_id:
            description: the id of the map this map is a fork of
            required: false
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/map.json
  patch:
    body:
      application/json:
        properties:
          name:
            description: name
            required: false
          desc:
            description: description
            required: false
          permission:
            description: commons, public, or private
            required: false
          screenshot:
            description: url to a screenshot of the map
            required: false
          source_id:
            description: the id of the map this map is a fork of
            required: false
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/map.json
  delete:
    responses:
      204:
        description: No content
  /stars:
    post:
      responses:
        201:
          description: Created
          body:
            application/json:
              example: !include ../examples/map_starred.json
    delete:
      responses:
        204:
          description: No content