openapi.yaml

swagger: '2.0'
info:
  title: Corvallis Parks API
  description: an api for the parks of Corvallis, OR
  version: v1
  license:
    name: GNU Affero General Public License Version 3
    url: http://www.gnu.org/licenses/agpl-3.0.en.html
  contact:
    name: David Kalcic
    email: kalcicd@oregonstate.edu
schemes:
  - https
host: api.oregonstate.edu
basePath: /v1
externalDocs:
  description: GitHub Repository
  url: https://github.com/osu-mist/parks-api
consumes:
  - application/json
produces:
  - application/json
paths:
  /parks:
    get:
      summary: List all parks
      tags:
        - parks
      description: Get all parks
      operationId: getParks
      parameters:
        - $ref: '#/parameters/filterAmenitiesAll'
        - $ref: '#/parameters/filterAmenitiesSome'
        - $ref: '#/parameters/filterName'
        - $ref: '#/parameters/filterCity'
        - $ref: '#/parameters/filterState'
        - $ref: '#/parameters/filterZip'
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/ParksResult'
        '400':
          $ref: '#/responses/400'
        '500':
          $ref: '#/responses/500'
    post:
      summary: Creates a new park
      tags:
        - parks
      operationId: createPark
      parameters:
      - $ref: '#/parameters/parkPostBody'
      responses:
        '201':
          description: Successfully created new park
          headers:
            Location:
              type: string
              description: Resource location of newly created park
          schema:
            $ref: '#/definitions/ParkResult'
        '400':
          $ref: '#/responses/400'
        '404':
          description: Referenced owner does not exist
          schema:
            $ref: '#/definitions/ErrorResult'
        '409':
          description: Conflict with type
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
  /parks/{parkId}:
    get:
      summary: Lists info for a specific park
      tags:
        - parks
      description: Get park by unique ID
      operationId: getParkById
      parameters:
        - $ref: '#/parameters/parkIdPath'
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/ParkResult'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
    patch:
      summary: Update information of a specific park
      tags: 
        - parks
      description: Update park by unique ID
      operationId: updateParkById
      parameters:
        - $ref: '#/parameters/parkIdPath'
        - $ref: '#/parameters/parkPatchBody'
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/ParkResult'
        '400':
          $ref: '#/responses/400'
        '404':
          $ref: '#/responses/404'
        '409':
          description: Invalid type, or id does not match path
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
    delete:
      summary: Delete a specific park
      tags: 
        - parks
      description: Delete park by unique ID
      operationId: deleteParkById
      parameters:
        - $ref: '#/parameters/parkIdPath'
      responses:
        '204':
          description: Park successfully deleted
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
  /owners:
    get:
      summary: Lists all park owners
      tags:
        - owners
      description: Get all park owners
      operationId: getOwners
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/OwnersResult'
        '500':
          $ref: '#/responses/500'
    post:
      summary: Creates a new park owner account
      tags:
        - owners
      description: Post a new park owner
      operationId: postOwner
      parameters:
      - $ref: '#/parameters/ownerPostBody'
      responses:
        '201':
          description: Successfully created new owner
          headers:
            Location:
              type: string
              description: Location of newly created owner
          schema:
            $ref: '#/definitions/OwnerResult'
        '400':
          $ref: '#/responses/400'
        '409':
          description: invalid type, or ownerName already in use
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
  /owners/{ownerId}:
    get:
      summary: gets the account of a park owner by ID
      tags:
        - owners
      description: gets park owner by ID
      operationId: getOwnerById
      parameters:
      - $ref: '#/parameters/ownerIdPath'
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/OwnerResult'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
    patch:
      summary: Updates the account of a park owner by ID
      tags:
        - owners
      description: patch park owner by ID
      operationId: updateOwnerById
      parameters:
      - $ref: '#/parameters/ownerIdPath'
      - $ref: '#/parameters/ownerPatchBody'
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/OwnerResult'
        '400':
          $ref: '#/responses/400'
        '404':
          $ref: '#/responses/404'
        '409':
          description: id and type cannot be changed. ownerName must also be unique.
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
    delete:
      summary: Delete a park owner account by ID
      tags:
        - owners
      description: Delete owner by ID
      operationId: deleteOwnerById
      parameters:
      - $ref: '#/parameters/ownerIdPath'
      responses:
        '204':
          description: Park successfully deleted
        '404':
          description: Owner resource not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
  /owners/{ownerId}/parks:
    get:
      summary: get parks by owner ID
      tags:
        - owners
      description: get parks by owner ID
      operationId: getParksByOwnerId
      parameters:
      - $ref: '#/parameters/ownerIdPath'
      - $ref: '#/parameters/filterAmenitiesAll'
      - $ref: '#/parameters/filterAmenitiesSome'
      - $ref: '#/parameters/filterName'
      - $ref: '#/parameters/filterCity'
      - $ref: '#/parameters/filterState'
      - $ref: '#/parameters/filterZip'
      responses:
        '200':
          description: Successful Response
          schema:
            $ref: '#/definitions/ParksResult'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
parameters:
  filterAmenitiesAll:
    in: query
    name: filter[amenities][all]
    description: Filter parks containing at least all of the listed amenities
    required: false
    type: array
    collectionFormat: csv
    items: &filterAmenitiesItems
      type: string
      enum: &amenitiesEnum
        - ballfield
        - barbequeGrills
        - basketballCourts
        - bikePaths
        - boatRamps
        - dogsAllowed
        - drinkingWater
        - fishing
        - hikingTrails
        - horseshoes
        - naturalArea
        - offleashDogPark
        - openFields
        - picnicShelters
        - picnicTables
        - playArea
        - restrooms
        - scenicViewPoint
        - soccerFields
        - tennisCourts
        - volleyball
  filterAmenitiesSome:
    in: query
    name: filter[amenities][some]
    description: Filter parks containing at least one of the listed amenities
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum: *amenitiesEnum
  filterName:
    in: query
    name: filter[name]
    description: Filter parks by name
    required: false
    type: string
  filterCity:
    in: query
    name: filter[city]
    description: Filter parks by city
    required: false
    type: string
  filterState:
    in: query
    name: filter[state]
    description: Filter parks by state (two letter abbreviation)
    required: false
    type: string
    pattern: &states '^(?:(A[KLRZ]|C[AOT]|D[CE]|FL|GA|HI|I[ADLN]|K[SY]|LA|M[ADEINOST]|N[CDEHJMVY]|O[HKR]|P[AR]|RI|S[CD]|T[NX]|UT|V[AIT]|W[AIVY]))$'
  filterZip:
    in: query
    name: filter[zip]
    description: Filter parks by zip code
    required: false
    type: integer
  ownerIdPath:
    in: path
    name: ownerId
    description: Unique Owner ID
    type: string
    pattern: '^[0-9]+$'
    required: true
  parkIdPath:
    name: parkId
    in: path
    description: Unique Park ID
    required: true
    type: string
    pattern: '^[0-9]+$'
  parkPostBody:
    name: parkBody
    in: body
    description: A park body object
    required: true
    schema:
      $ref: '#/definitions/PostParkModel'
  parkPatchBody:
    name: parkBody
    in: body
    description: A park body object
    required: true
    schema:
      $ref: '#/definitions/PatchParkModel'
  ownerPostBody:
    name: ownerPostBody
    in: body
    description: An owner body object
    required: true
    schema:
      $ref: '#/definitions/PostOwnerModel'
  ownerPatchBody:
    name: ownerPatchBody
    in: body
    description: An owner body object
    required: true
    schema:
      $ref: '#/definitions/PatchOwnerModel'
definitions:
  SelfLink:
    properties:
      self:
        type: string
        format: uri
        description: Self-link of current resource
  OwnerResource:
    required: [id, type, links, attributes]
    properties:
      id: &ownerId
        type: string
        minLength: 1
        example: '0001'
        description: A unique ID of a park owner
      type: &ownerType
        type: string
        description: type of object, should be owner
        enum: [owner]
      links: &resourceSelfLink
        type: object
        description: links to resource
        properties:
          self:
            type: string
            format: uri
            description: self-link to resource
      attributes: &ownerAttributes
        required: [ownerName]
        properties:
          ownerName:
            type: string
            minLength: 1
            description: Name of park owner / organization
            example: City of Corvallis
  PostOwnerModel:
    required: [data]
    properties:
      data:
        required: [type, attributes]
        properties:
          type: *ownerType
          attributes: *ownerAttributes
  PatchOwnerModel:
    required: [data]
    properties:
      data:
        required: [id, type]
        properties:
          id: *ownerId
          type: *ownerType
          attributes: *ownerAttributes
  ParkResource:
    required: [id, type, links, attributes, relationships]
    properties:
      id: &parkId
        type: string
        minLength: 1
        example: '0001'
        description: A unique ID of park
      type: &parkType
        type: string
        description: type of object, should be park
        enum: [park]
      links: *resourceSelfLink
      attributes: &parkAttributes
        required: [name, location, amenities]
        properties:
          name: &parkName
            type: string
            minLength: 1 
            description: Name of Park
            example: Avery Park
          location:
            type: object
            required: [streetAddress, city, state, zip, latitude, longitude]
            properties:
              streetAddress: &streetAddress
                type: string
                minLength: 1
                description: Park address
                example: '1200 SW Avery Park Dr.'
              city: &city
                type: string
                minLength: 1
                description: City where the park is located
                example: Corvallis
              state: &state
                type: string
                description: Abbreviation of state where park is located
                pattern: *states
                example: OR
              zip: &zip
                type: integer
                description: Zip code where park is located
                example: 97333
              latitude: &latitude
                type: number
                format: float
                description: latitude of park
                example: 44.552283
              longitude: &longitude
                type: number
                format: float
                description: longitude of park
                example: -123.269906
          amenities: &amenities
            type: array
            items:
              enum: *amenitiesEnum
              type: string
            description: list of amenities at park
      relationships: &parkRelationships
        type: object
        required: [owner]
        properties:
          owner:
            type: object
            required: [data]
            properties:
              data:
                type: object
                required: [type, id]
                properties:
                  type:
                    type: string
                    enum: [owner]
                  id:
                    type: string
                    pattern: '^[0-9]+$'
                    example: '1111'
  PostParkModel:
    required: [data]
    properties:
      data:
        type: object
        required: [type, attributes, relationships]
        properties:
          type: *parkType
          attributes: *parkAttributes
          relationships: *parkRelationships
  PatchParkModel:
    required: [data]
    properties:
      data:
        type: object
        required: [id, type]
        properties:
          id: *parkId
          type: *parkType
          attributes:
            properties:
              name: *parkName
              location:
                type: object
                properties:
                  streetAddress: *streetAddress
                  city: *city
                  state: *state
                  zip: *zip
                  latitude: *latitude
                  longitude: *longitude
              amenities: *amenities
          relationships: *parkRelationships
  ErrorObject:
    properties:
      status:
        type: string
        description: HTTP status code
        example: '123'
      title:
        type: string
        description: A short, user readable summary of the error
        example: 'Not Found'
      code:
        type: string
        description: An application-specific error code
        example: '1234'
      detail:
        type: string
        description: A long description of the error that may contain instance-specific details
        example: A long description of the error that may contain instance-specific details
      links:
        properties:
          about:
            type: string
            format: uri
            description: A link to further information about the error
            example: 'https://developer.oregonstate.edu/documentation/error-reference#1234'
  ParkResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/ParkResource'
  ParksResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        type: array
        items:
          $ref: '#/definitions/ParkResource'
  OwnerResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/OwnerResource'
  OwnersResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        type: array
        items:
          $ref: '#/definitions/OwnerResource'
  ErrorResult:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ErrorObject'
responses:
  '400':
    description: Incorrect syntax in request, or required fields missing
    schema:
      $ref: '#/definitions/ErrorResult'
  '404':
    description: Resource not found
    schema:
      $ref: '#/definitions/ErrorResult'
  '500':
    description: Internal server error
    schema:
      $ref: '#/definitions/ErrorResult'