API Design

An intro to the what, why, and how.

Created by Douglas Mason & Matthew Orres

WHAT & WHY

Most Popular Design Languages

RAML -> YAML

			
#%RAML 0.8
 
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
  - paged:
      queryParameters:
        pages:
          description: The number of pages to return
          type: number
  - secured: !include http://raml-example.com/secured.yml
/songs:
  is: [ paged, secured ]
  get:
    queryParameters:
      genre:
        description: filter the songs by genre
  post:
  /{songId}:
    get:
      responses:
        200:
          body:
            application/json:
              schema: |
                { "$schema": "http://json-schema.org/schema",
                  "type": "object",
                  "description": "A canonical song",
                  "properties": {
                    "title":  { "type": "string" },
                    "artist": { "type": "string" }
                  },
                  "required": [ "title", "artist" ]
                }
            application/xml:
    delete:
      description: |
        This method will *delete* an **individual song**
			
			

API Blueprint

Markdown

			

# GET /message
+ Response 200 (text/plain)

        Hello World!
			
			

Resulting JSON

		
{
    "_version": "2.0",
    "metadata": [],
    "name": "",
    "description": "",
    "resourceGroups": [
        {
            "name": "",
            "description": "",
            "resources": [
                {
                    "name": "",
                    "description": "",
                    "uriTemplate": "/message",
                    "model": {},
                    "parameters": [],
                    "actions": [
                        {
                            "name": "",
                            "description": "",
                            "method": "GET",
                            "parameters": [],
                            "examples": [
                                {
                                    "name": "",
                                    "description": "",
                                    "requests": [],
                                    "responses": [
                                        {
                                            "name": "200",
                                            "description": "",
                                            "headers": [
                                                {
                                                    "name": "Content-Type",
                                                    "value": "text/plain"
                                                }
                                            ],
                                            "body": "Hello World!\n",
                                            "schema": ""
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
		
		
		

THE END