Overview

Welcome to the the DevCon Star Wars API! This documentation should help you familiarise yourself with the resources available and how to consume them with HTTP requests.

May the force be with you, always.

— Star Wars: Episode IV A New Hope

HTTP verbs

DevCon Starwars API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PATCH`	Used to update an existing resource, including partial updates
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

DevCon Starwars API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

Status code	Usage
`200 OK`	The request completed successfully
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s `Location` header
`204 No Content`	An update to an existing resource has been applied successfully
`400 Bad Request`	The request was malformed. The response body will include an error providing further information
`404 Not Found`	The requested resource does not exist

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource does not exist

Headers

Every response has the following header(s):

Name Description

Name	Description
`Content-Type`	The Content-Type of the payload, e.g. `application/hal+json`

Content-Type

The Content-Type of the payload, e.g. application/hal+json

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

Path	Type	Description
`error`	`String`	The HTTP error that occurred, e.g. `Not Found`
`message`	`String`	A description of the cause of the error
`path`	`String`	The path to which the request was made
`status`	`Number`	The HTTP status code, e.g. `400`
`timestamp`	`Number`	The time, in milliseconds, at which the error occurred

error

String

The HTTP error that occurred, e.g. Not Found

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

Number

The time, in milliseconds, at which the error occurred

For example, a request to create a planet with incorrect information results in a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "timestamp" : 1532327998501,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Validation failed. Field 'name' must not be null.",
  "path" : "/planets"
}

DevCon Starwars API uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application from resource to resource. Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate

Resources

Path	Type	Description
`_links`	`Object`	Links to other resources

Object

Links to other resources

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 225

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/"
    },
    "planets" : {
      "href" : "http://localhost:8080/planets"
    },
    "people" : {
      "href" : "http://localhost:8080/people"
    }
  }
}

Links

Relation Description

Relation	Description
`self`	The resource itself
`planets`	The Planets resource
`people`	The People resource

self

The resource itself

planets

The Planets resource

people

The People resource

Path	Type	Description
`_embedded.planets`	`Array`	A list of Planet resources
`_links`	`Object`

Array

A list of Planet resources

_links

Object

Example request

$ curl 'http://localhost:8080/planets' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 521

{
  "_embedded" : {
    "planets" : [ {
      "id" : 13,
      "name" : "Alderaan",
      "population" : 2000000000,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/planets/13"
        }
      }
    }, {
      "id" : 14,
      "name" : "Naboo",
      "population" : 4500000000,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/planets/14"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/planets"
    }
  }
}

Creating a planet

A POST request is used to create a planet.

Request fields

Path Type Description

Path	Type	Description
`id`	`Null`	Planet’s ID
`name`	`String`	Planet’s name
`population`	`Number`	Planet’s population

id

Null

Planet’s ID

name

String

Planet’s name

population

Number

Planet’s population

Example request

$ curl 'http://localhost:8080/planets' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{"id":null,"name":"Kamino","population":0}'

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/planets/50

Path	Type	Description
`id`	`Number`	Id of the planet
`name`	`String`	Name of the planet
`population`	`Number`	Planet’s population

Number

Id of the planet

name

String

Name of the planet

population

Number

Planet’s population

Example request

$ curl 'http://localhost:8080/planets/55' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 158

{
  "id" : 55,
  "name" : "Alderaan",
  "population" : 2000000000,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/planets/55"
    }
  }
}

Update a planet

A PATCH request is used to update a planet

Request structure

Path Type Description

Path	Type	Description
`name`	`String`	Planet’s name
`population`	`Number`	Planet’s population

name

String

Planet’s name

population

Number

Planet’s population

To leave an attribute of a planet unchanged, any of the above may be omitted from the request.

Example request

$ curl 'http://localhost:8080/planets/29' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{"name":"Kamino","population":1000000000}'

Example response

HTTP/1.1 204 No Content

Path	Type	Description
`_embedded.persons`	`Array`	A list of Person resources
`_links`	`Object`

Array

A list of Person resources

_links

Object

Example request

$ curl 'http://localhost:8080/people' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 467

{
  "_embedded" : {
    "persons" : [ {
      "id" : 39,
      "name" : "Luke Skywalker",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/39"
        }
      }
    }, {
      "id" : 40,
      "name" : "Obi-Wan Kenobi",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/40"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people"
    }
  }
}

Creating a person

A POST request is used to create a person.

Request fields

Path Type Description

Path	Type	Description
`id`	`Null`	Person’s ID
`name`	`String`	Person’s name

id

Null

Person’s ID

name

String

Person’s name

Example request

$ curl 'http://localhost:8080/people' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{"id":null,"name":"Kamino"}'

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/people/45

Path	Type	Description
`id`	`Number`	Person’s id
`name`	`String`	Person’s name

Number

Person’s id

name

String

Person’s name

Example request

$ curl 'http://localhost:8080/people/53' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 134

{
  "id" : 53,
  "name" : "Luke Skywalker",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/53"
    }
  }
}

Update a person

A PATCH request is used to update a person

Request structure

Path Type Description

Path	Type	Description
`name`	`String`	Person’s name

name

String

Person’s name

To leave an attribute of a person unchanged, any of the above may be omitted from the request.

Example request

$ curl 'http://localhost:8080/people/27' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{"name":"C-3PO"}'

Example response

HTTP/1.1 204 No Content

DevCon REST TDD Demo