API Template: RAML Endpoint

api.raml

# replace {{resource}} by the name of the resource
# replace {{secured}} by the appropiate authorization trait name, i.e. 'secured', 'auth', etc...


traits:
  - {{secured}}:
      queryParameters:
        # authorization query params
      headers:
        # authorization headers

schemas:
  - {{resource}}: |
      {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {
            # schema properties
          },
        "required": [
          # required properties
        ],  
        "additionalProperties": false    
      }


/{{resource}}:
  get:
    description: Lists the {{resource}}s associated with the agent
    is: ['{{secured}}']
    responses:
      200:
        body:
          application/json:
            example: | 
              {
                "data": {
                  "{{resource}}s":[
                    # example resource list
                  ]
                },
                "isSuccessful": true,
                "message": ""
              }
      401:
        body:
          application/json:
            example: |
              {
                "data": {},
                "isSuccessful": false,
                "message": "Invalid token"
              }
      500:
        body:
          application/json:
            example: |
              {
                "data": {},
                "isSuccessful": false,
                "message": "Service Unavailable"
              }
  post:
    description: Associates a {{resource}} to a given agent
    is: ['{{secured}}']
    body:
      application/json:
        schema: {{resource}}
        example:  |
          {
            # example resource
          } 
    responses:
      201:
        body:
          application/json:
            example: | 
              {
                "data": {
                  "id": 1
                },
                "isSuccessful": true,
                "message": ""
              }
      401:
        body:
          application/json:
            example: |
              {
                "data": {},
                "isSuccessful": false,
                "message": "Invalid token"
              }
      500:
        body:
          application/json:
            example: |
              {
                "data": {},
                "isSuccessful": false,
                "message": "Service Unavailable"
              }
  /{{{resource}}Id}:
    get:
      description: Returns a given {{resource}}
      is: ['{{secured}}']
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "data": {
                    # example resource
                  },
                  "isSuccessful": true,
                  "message": ""
                }
        401:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": false,
                  "message": "Invalid token"
                }
        500:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": false,
                  "message": "Service Unavailable"
                }
    put:
      description: Updates a given {{resource}} resource
      is: ['{{secured}}']
      body:
        application/json:
          schema: {{resource}}
          example:  |
            {
              # example resource
            }            
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": true,
                  "message": ""
                }
        401:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": false,
                  "message": "Invalid token"
                }
        500:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": false,
                  "message": "Service Unavailable"
                }
    delete:
      description: Deletes a given {{resource}} resource
      is: ['{{secured}}']
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": true,
                  "message": ""
                }
        401:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": false,
                  "message": "Invalid token"
                }
        500:
          body:
            application/json:
              example: |
                {
                  "data": {},
                  "isSuccessful": false,
                  "message": "Service Unavailable"
                }