RAML 1.0 Contract first example

README.md

RAML 1.0 contract first example

RAML 1.0 is coming our way, and the new features it provide may allow us to use it as a contract for our APIs.

Using types and annotationTypes, we can, for example, describe a controller that will be resolved for each of our methods.

Here is an example:

#%RAML 1.0
title: A demo RAML definition
mediaType: application/json

annotationTypes:
  controller:
    description: The controller to resolve for a given resource.  
    allowedTargets: [ Method ]
    type: string
    required: true
types:
  User:
    type: object
    properties:
      username: string
      firstname: string
      lastname: string
      email: string

# Available resources
/users:
    get:
      description: Get all users
      (controller): MyApp\Action\User\GetUsers
      responses:
        200:
          body:
            application/json:
              type: User[]

    # Users sub-resources
    /{userId}:
      uriParameters:
        userId:
          type: integer
          required: true
      get:
        description: Get one user by Id
        (controller): MyApp\Action\User\GetUser
        responses:
          200:
            body:
              application/json:
                type: User