api.raml

#%RAML 1.0
title: Customer Management
version: v1
protocols: [HTTPS]
baseUri: https://api.samplehost.com/api/{version}
mediaType: application/json
description: !
  "API specification for managing customers"
securedBy: oauth_2_0

###################
## Security Schemes
###################
securitySchemes:
  basic: !include securitySchemes/basic.raml
  oauth_2_0: !include securitySchemes/oauth_2_0.raml


###################
## Types
###################
types:
  customer:
    description: Model for 'Customer' resource
    schema: !include schemas/customer.schema

  errorResponse:
    description: Standard model for all error responses (irrespective of the code)
    schema: !include schemas/errorResponse.schema

  successResponse:
    description: Standard response model for all success responses
    schema: !include schemas/successResponse.schema


  paginatedResponse:
    description: |
      Standard model for paginated response.\n
      The paginated response contain necessary attributes which will indicate to the consumer how many times they will need to invoke to API to obtain the complete resultset.
    schema: !include schemas/paginatedResponse.schema



###################
## Traits
###################
traits:
  pageable: !include traits/pageable.raml
  sortable: !include traits/sortable.raml
  throwsForbiddenError: !include traits/throwsForbiddenError.raml
  throwsResourceNotFoundError: !include traits/throwsResourceNotFoundError.raml
  throwsInternalServerError: !include traits/throwsInternalServerError.raml
  makeConditionalRequests: !include traits/makeConditionalRequests.raml
  allowPatch:
    description: |
      Allow partial modification of <<resourcePathName | !singularize>>
    body: <<examplePatchResourceBody>>
    responses:
      204:
        description: Return the updated <<resourcePathName | !singularize>> resource
        body:
          application/json:
            example: <<patchResourceResponseExample>>
            type: <<patchResourceResponseType>>


###################
## Resource Types
###################
resourceTypes:
  collectionType: !include resourceTypes/collection.raml
  resourceType: !include resourceTypes/resource.raml


###################
## API Definitions
###################
/customers:
  displayName: Customer collection
  description: Set of APIs to manage Customer resource.
  type:  {
            collectionType:
              {
                examplePaginatedResponseExample : !include examples/getCustomerPaginatedResponse-example.json,
                examplePaginatedResponseType: paginatedResponse,

                createResourceRequestExample : !include examples/customer-example.json,
                createResourceRequestType: customer,

                createResourceResponseExample: !include examples/createCustomerResponse-example.json,
                createResourceResponseType: successResponse,

                createResourceBadRequestExample: !include examples/400-createCustomerBadRequest-example.json
              }
        }
  get:
    is: [pageable,sortable]
    description: |
      Retrieve all customers. When query parameters are ommited, the API calls returns all customers. Using the optional query
      parameters, the result set could be narrowed further to the matching customers.

    queryParameters:
      firstName:
        required: false
        description: First name of customer
        type: string
        example: John
      lastName:
        required: false
        description: Last name of customer
        type: string
        example: Smith
      address.streetLine1:
        required: false
        description: Fuzzy search on street line 1
        type: string
        example: George Street
      address.streetLine2:
        required: false
        description: Fuzzy search on street line 2
        type: string
        example: Mountain%20Street
      address.city:
        required: false
        description: Fuzzy search address
        type: string
        example: Sydney, Bellevue%20Hill, Potts%20Point
      address.postCode:
        required: false
        description: Exact search by postcode
        type: string
        example: 2000, 214


  /{customerId}:
    displayName: Customer resource
    securedBy: oauth_2_0
    description: Operations on individual Customer resource

    type:  {
      resourceType:
          {
            updateResourceRequestExample : !include examples/customer-example.json,
            updateResourceRequestType: customer,

            updateResourceResponseExample: !include examples/customer-example.json,
            updateResourceResponseType: customer,

            getSingleResourceExample: !include examples/customer-example.json,
            getSingleResourceType: customer
          }
      }
    get:
      is: [ makeConditionalRequests]
    patch:
      is:  [allowPatch: {
          examplePatchResourceBody : !include examples/patchCustomer-example.json,
          patchResourceResponseExample : !include examples/customer-example.json,
          patchResourceResponseType : customer
        }]