Introduction

This API is a REST API. It is built on HTTP standards, with intuitive URIs, leveraging HTTP response codes and HTTP verbs that can be consumed by off-the-shelf HTTP clients. It uses cross-origin resource sharing (CORS) to support secure interactions between your client and our resources. All responses are in JSON format, including payloads associated with errors.

API Endpoint

https://api.example.com

Versioning

By default, all requests receive the latest version of the API. We encourage you to explicitly request a version by date via the Accept header. When requesting a resource via a date, you are able to get the latest version, as of the time that you are developing. Future changes to the API will be ignored by your client, unless you change the date.

Accept Header with Version

Accept: application/json;version=20150820

Example Request

curl -X GET "http://localhost:3001/example/legos" -H "Accept: application/json;version=20150828" -H "Cache-Control: no-cache"

var request = require("request"),
    options;

options = {
    "method": "GET",
    "url": "http://localhost:3001/example/legos",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
};

request(options, function (err, response, body) {
    if (err) {
        return console.log(err);
    }

    console.log(body);
});

var options = {
    "method": "GET",
    "mode": "cors",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
};

fetch('http://localhost:3001/example/legos', options)
   .then(function (res) {
        return res.json();
    }).then(function (res) {
        console.log(res);
    });


package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "http://localhost:3001/example/legos"
  req, _ := http.NewRequest("GET", url, payload)

  req.Header.Add("Accept", "application/json;version=20150828")
  req.Header.Add("Cache-Control", "no-cache")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body)) 
}

You can check the current version through every response’s headers. Look for the X-API-Version header:

Example Response Header

X-API-Version: 20150820

Important: The default version of the API may change in the future. If you're building an application and care about the stability of the API, be sure to request a specific version in the Accept header as shown in the examples.

HTTP Status Codes

This API uses these HTTP Status codes

Error Code Meaning
200 Success -- rejoice
201 Created -- a new resource was created successfully
202 Accepted -- The request was accepted and queued, actual success will be delivered via notifications
400 Bad Request -- Umm. I don't know. Who am I?
401 Unauthorized -- Did you authenticate first? Do you have a JWT token in your headers?
403 Forbidden -- You are not authorized to access the resource you requested
404 Not Found -- The endpoint could not be found
405 Method Not Allowed -- The method/verb you requested is not supported
406 Not Acceptable -- You requested a format that isn't JSON
410 Gone -- The resource was removed from our servers
418 I'm a teapot
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Legos

This section provides an example for documenting a data-type.

Legos /example/legos are ... They have the following schema:

Property Type Description
color string The color of the lego
width int The number of connectors the lego has, in width
length int The number of connectors the lego has, in length
height int An integer representation of the height

Example Lego

{
    "color": "red",
    "width": 2,
    "length": 6,
    "height": 2
}

List Legos GET

This endpoint retrieves all Legos GET http://api.example.com/legos/.

Example Request

{
    "method": "GET",
    "protocol": "http",
    "host": "localhost:3001",
    "path": "/example/legos",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
}

Example Response 200

[
    { "color": "red", "width": 2, "length": 6, "height": 2 },
    { "color": "green", "width": 2, "length": 6, "height": 2 },
    { "color": "blue", "width": 2, "length": 6, "height": 2 }
]

Get Lego GET

This endpoint retrieves a single Lego GET http://api.example.com/legos/:id.

Parameters

Name Type Description
id int The id of the lego you wish to retrieve

Example Request

curl -X GET "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8" -H "Accept: application/json;version=20150828" -H "Cache-Control: no-cache"

var request = require("request"),
    options;

options = {
    "method": "GET",
    "url": "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
};

request(options, function (err, response, body) {
    if (err) {
        return console.log(err);
    }

    console.log(body);
});

var options = {
    "method": "GET",
    "mode": "cors",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
};

fetch('http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8', options)
   .then(function (res) {
        return res.json();
    }).then(function (res) {
        console.log(res);
    });


package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8"
  req, _ := http.NewRequest("GET", url, payload)

  req.Header.Add("Accept", "application/json;version=20150828")
  req.Header.Add("Cache-Control", "no-cache")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body)) 
}

Example Response 200

{
    "color": "red",
    "width": 2,
    "length": 6,
    "height": 2
}

Create Lego POST

This endpoint creates a Lego POST http://api.example.com/legos/.

Body

The body of your request should include a Lego.

Example Request

curl -X POST "http://localhost:3001/example/legos" -H "Accept: application/json;version=20150828" -H "Cache-Control: no-cache" -d '{ "color": "yellow", "width": 2, "length": 6, "height": 2 }'

var request = require("request"),
    options;

options = {
    "method": "POST",
    "url": "http://localhost:3001/example/legos",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    },
    "body": "{ \"color\": \"yellow\", \"width\": 2, \"length\": 6, \"height\": 2 }"
};

request(options, function (err, response, body) {
    if (err) {
        return console.log(err);
    }

    console.log(body);
});

var options = {
    "method": "POST",
    "mode": "cors",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    },
    "body": "{ \"color\": \"yellow\", \"width\": 2, \"length\": 6, \"height\": 2 }"
};

fetch('http://localhost:3001/example/legos', options)
   .then(function (res) {
        return res.json();
    }).then(function (res) {
        console.log(res);
    });


package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "http://localhost:3001/example/legos"
  payload := strings.NewReader("{ \"color\": \"yellow\", \"width\": 2, \"length\": 6, \"height\": 2 }")
  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Accept", "application/json;version=20150828")
  req.Header.Add("Cache-Control", "no-cache")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body)) 
}

Example Response 201

{
    "color": "yellow",
    "width": 2,
    "length": 6,
    "height": 2
}

Example Response 400. This response would be generated if you omitted the height property, or if you provided a height that isn't a number.

{
    "type": "InvalidArgumentException",
    "messages": ["This implementation does not satisfy blueprint, Lego. It should have the property, height, with type, number."],
    "isException": true
}

Update Lego PUT

This endpoint creates a Lego PUT http://api.example.com/legos/:id.

Body

The body of your request should include a Lego.

Example Request

curl -X PUT "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8" -H "Accept: application/json;version=20150828" -H "Cache-Control: no-cache" -d '{ "color": "yellow", "width": 2, "length": 6, "height": 2 }'

var request = require("request"),
    options;

options = {
    "method": "PUT",
    "url": "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    },
    "body": "{ \"color\": \"yellow\", \"width\": 2, \"length\": 6, \"height\": 2 }"
};

request(options, function (err, response, body) {
    if (err) {
        return console.log(err);
    }

    console.log(body);
});

var options = {
    "method": "PUT",
    "mode": "cors",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    },
    "body": "{ \"color\": \"yellow\", \"width\": 2, \"length\": 6, \"height\": 2 }"
};

fetch('http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8', options)
   .then(function (res) {
        return res.json();
    }).then(function (res) {
        console.log(res);
    });


package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8"
  payload := strings.NewReader("{ \"color\": \"yellow\", \"width\": 2, \"length\": 6, \"height\": 2 }")
  req, _ := http.NewRequest("PUT", url, payload)

  req.Header.Add("Accept", "application/json;version=20150828")
  req.Header.Add("Cache-Control", "no-cache")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body)) 
}

Example Response 200

{
    "color": "yellow",
    "width": 2,
    "length": 6,
    "height": 2
}

Example Response 400. This response would be generated if you omitted the height property, or if you provided a height that isn't a number.

{
    "type": "InvalidArgumentException",
    "messages": ["This implementation does not satisfy blueprint, Lego. It should have the property, height, with type, number."],
    "isException": true
}

Delete Lego DELETE

This endpoint deletes a Lego DELETE http://api.example.com/legos/:id.

Example Request

curl -X DELETE "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8" -H "Accept: application/json;version=20150828" -H "Cache-Control: no-cache"

var request = require("request"),
    options;

options = {
    "method": "DELETE",
    "url": "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
};

request(options, function (err, response, body) {
    if (err) {
        return console.log(err);
    }

    console.log(body);
});

var options = {
    "method": "DELETE",
    "mode": "cors",
    "headers": {
        "Accept": "application/json;version=20150828",
        "Cache-Control": "no-cache"
    }
};

fetch('http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8', options)
   .then(function (res) {
        return res.json();
    }).then(function (res) {
        console.log(res);
    });


package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "http://localhost:3001/example/legos/5EC3C1E7-8237-4BE9-8B98-3B049E2F9AE8"
  req, _ := http.NewRequest("DELETE", url, payload)

  req.Header.Add("Accept", "application/json;version=20150828")
  req.Header.Add("Cache-Control", "no-cache")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body)) 
}

Example Response 200

// no body

Example Response 400. This response would be generated if you attempted to delete an id that doesn't exist.

{
    "type": "InvalidArgumentException",
    "messages": ["The index cannot be deleted: it does not exist"],
    "isException": true
}

About

This documentation is rendered from Git Flavored Markdown (GFM), using marked and hightlight.js. The docs can be found in the ./docs folder. To add a document, add a path to it in the ./environment/environment.json file, in the docs.files object.

This engine supports language-switching. To set your supported languages, set the docs.languages object in the ./environment/environment.json file. If you only support a single language, this object can be omitted from the environment.json file. The languge schema follows:

Property Type Description
name string The name as you would like it to appear in the Language Menu
highlightClass string The class name that highlight.js transforms the markdown to

Example Language

{
    "name": "JavaScript",
    "highlightClass": "lang-js"
}

Conventions

Code Blocks

Since we're using highlight.js to color the code blocks, you'll want to make sure to add your language to your code block ticks:

```js
// ...

Blockquote Headings

To get the code-block-header styles in this guide, use blockquote heading combos.

In the future, we may support side-by-side text-code layouts. The blockquotes and code blocks will be displayed in the side-bar, so make sure you take advantage of these conventions if you're interested in using the other layout options.

> # Code Block Header

It looks like this:

Code Block Header

console.log('hello world!');

There's also a blockquote h2 combo, meant to be used with code blocks

> ## Code Info

It looks like this:

Code Block H1

console.log('hello world!');

Code Block H2

Alterations

Once the markdown is rendered, we convert the #### (h4) and ##### (h5) layout into notifications and warnings:

Example Info: We convert h4 elements #### to info alerts.

Example Warning: We convert h5 elements ##### to danger alerts.

If you would prefer that your h4 and h5 styles not be altered, set docs.useHeadingAlerts to false in your environment.json file.