API Endpoints

Rooms

Get room

GET http://comp3220.ecs.soton.ac.uk/rooms/{room_id}

Retrieve the information about a room

Parameters

Name Type Location Description
room_id integer URL Unique id for a room

Response Fields

Field Type Description
url string URL for this room
number string Identifier for this room
description string Describes the functionality and usage of the room
capacity integer Maximum number of people in a room
building string Building URL in which this room is located in

Example Request

GET http://comp3220.ecs.soton.ac.uk/rooms/1

Example Response

200 OK

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/rooms/1",
									    "number": "58-1023",
									    "description": "Common Learning Space: Murray Lecture Room G",
									    "capacity": 10,
									    "building": "http://comp3220.ecs.soton.ac.uk/buildings/64"
									}

Get list of rooms

GET http://comp3220.ecs.soton.ac.uk/rooms/

Retrieve the information of all rooms

Response Fields

The response will be a list of rooms, each with the following fields:

Field Type Description
url string URL for this room
number string Identifier for this room
description string Describes the functionality and usage of the room
capacity integer Maximum number of people in a room
building string Building URL in which this room is located in

Example Request

GET http://comp3220.ecs.soton.ac.uk/rooms

Example Response

200 OK

									[
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/rooms/1",
									        "number": "58-1023",
									        "description": "Common Learning Space: Murray Lecture Room G",
									        "capacity": 10,
									        "building": "http://comp3220.ecs.soton.ac.uk/buildings/64"
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/rooms/2",
									        "number": "6-1131",
									        "description": "Nuffield L/R E - blocked out for Music",
									        "capacity": 19,
									        "building": "http://comp3220.ecs.soton.ac.uk/buildings/96"
									    },

									    ...

									]

Create new room

POST http://comp3220.ecs.soton.ac.uk/rooms/

Creates a new room

Parameters

Name Type Location Description
Authorization string Header Client's authorization token

Request Fields

Field Type Description
building string Building URL in which this room is located in
capacity integer Maximum number of people in a room
number string Identifier for this room
description string Describes the functionality and usage of the room

Response Fields

The response will be a list of rooms, each with the following fields:

Field Type Description
url string URL for this room
number string Identifier for this room
description string Describes the functionality and usage of the room
capacity integer Maximum number of people in a room
building string Building URL in which this room is located in

Example Request

POST http://comp3220.ecs.soton.ac.uk/rooms/

									{
									    "number": "200-3220",
									    "description": "CLS for ECS students",
									    "capacity": 44,
									    "building": "http://comp3220.ecs.soton.ac.uk/buildings/187"
									}

Example Response

201 Created

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/rooms/265",
									    "number": "200-3220",
									    "description": "CLS for ECS students",
									    "capacity": 44,
									    "building": "http://comp3220.ecs.soton.ac.uk/buildings/187"
									}

Update room information

PUT http://comp3220.ecs.soton.ac.uk/rooms/{room_id}

PATCH http://comp3220.ecs.soton.ac.uk/rooms/{room_id}

There are two methods that can be used to update the information for a room: PUT and PATCH. PUT requires all of the information stated in the Request Fields to be present, while PATCH does not require all of stated fields to be present. In both cases, the format for Parameters, Request Fields and Response Fields are the same.

Parameters

Name Type Location Description
room_id integer URL Unique id for a room
Authorization string Header Client's authorization token

Request Fields *

Field Type Description
building string Building URL in which this room is located in
capacity integer Maximum number of people in a room
number string Identifier for this room
description string Describes the functionality and usage of the room
*The request fields are mandatory for PUT requests only.

Response Fields

The response will be a list of rooms, each with the following fields:

Field Type Description
url string URL for this room
number string Identifier for this room
description string Describes the functionality and usage of the room
capacity integer Maximum number of people in a room
building string Building URL in which this room is located in

Example Request

PUT/PATCH http://comp3220.ecs.soton.ac.uk/rooms/265

									{
									    "number": "200-3220",
									    "description": "CLS for ECS students",
									    "capacity": 50,
									    "building": "http://comp3220.ecs.soton.ac.uk/buildings/187"
									}

Example Response

200 OK

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/rooms/265",
									    "number": "200-3220",
									    "description": "CLS for ECS students",
									    "capacity": 50,
									    "building": "http://comp3220.ecs.soton.ac.uk/buildings/187"
									}

Delete room

DELETE http://comp3220.ecs.soton.ac.uk/rooms/{room_id}

Delete a room

Parameters

Namer Type Location Description
room_id integer URL Unique id for this room
Authorization string Header Client's authorization token

Example Request

DELETE http://comp3220.ecs.soton.ac.uk/rooms/2

Example Response

204 No Content

Buildings

Get building

GET http://comp3220.ecs.soton.ac.uk/buildings/{building_id}

Retrieve the information about a building

Parameters

Name Type Location Description
building_id integer URL Unique id for a building

Response Fields

Field Type Description
url string URL for this building
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building
site string URL for the site in which this building is located in
rooms string URL for the list of rooms located in this building

Example Request

GET http://comp3220.ecs.soton.ac.uk/buildings/2

Example Response

200 OK

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/buildings/2",
									    "name": "Cycle store near B39",
									    "number": "39A",
									    "latitude": "50.937",
									    "longitude": "-1.399",
									    "site": "http://comp3220.ecs.soton.ac.uk/sites/4",
									    "rooms": "http://comp3220.ecs.soton.ac.uk/buildings/2/rooms"
									}

Get list of buildings

GET http://comp3220.ecs.soton.ac.uk/buildings/

Retrieve the information of all buildings

Response Fields

The response will be a list of buildings, each with the following fields:

Field Type Description
url string URL for this building
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building
site string URL for the site in which this building is located in
rooms string URL for the list of rooms located in this building

Example Request

GET http://comp3220.ecs.soton.ac.uk/buildings/2

Example Response

200 OK

									[
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/buildings/1",
									        "name": "158 Mayfield Road",
									        "number": "1622",
									        "latitude": "50.937",
									        "longitude": "-1.390",
									        "site": "http://comp3220.ecs.soton.ac.uk/sites/4",
									        "rooms": "http://comp3220.ecs.soton.ac.uk/buildings/1/rooms"
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/buildings/2",
									        "name": "Cycle store near B39",
									        "number": "39A",
									        "latitude": "50.937",
									        "longitude": "-1.399",
									        "site": "http://comp3220.ecs.soton.ac.uk/sites/4",
									        "rooms": "http://comp3220.ecs.soton.ac.uk/buildings/2/rooms"
									    },

									    ...
									]

Get list of rooms in a building

GET http://comp3220.ecs.soton.ac.uk/buildings/{building_id}/rooms

Returns the list of rooms located within a specific building

Parameters

Name Type Location Description
building_id integer URL Unique id for a building

The response will be a list of rooms, each with the following fields

Response Fields

Field Type Description
url string URL for this room
number string Identifier for this room
description string Describes the functionality and usage of the room
capacity integer Maximum number of people in a room

Example Request

GET http://comp3220.ecs.soton.ac.uk/buildings/187/room

Example Response

200 OK

									[
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/rooms/265",
									        "number": "200-3220",
									        "description": "CLS for ECS students",
									        "capacity": 58
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/rooms/268",
									        "number": "123",
									        "description": "CLS for ECS students",
									        "capacity": 44
									    },

									    ...
									]

Create new building

POST http://comp3220.ecs.soton.ac.uk/buildings/

Creates a new building

Parameters

Name Type Location Description
Authorization string Header Client's authorization token

Request Fields

Field Type Description
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building
site string URL for the site in which this building is located in

Response Fields

Field Type Description
url string URL for this building
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building
site string URL for the site in which this building is located in
rooms string URL for the list of rooms located in this building

Example Request

POST http://comp3220.ecs.soton.ac.uk/buildings/

									{
									    "name": "547 Burgess Road",
									    "number": "547",
									    "latitude": "15.670",
									    "longitude": "-11.345",
									    "site": "http://comp3220.ecs.soton.ac.uk/sites/4",
									}

Example Response

201 Created

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/buildings/200",
									    "name": "547 Burgess Road",
									    "number": "547",
									    "latitude": "15.670",
									    "longitude": "-11.345",
									    "site": "http://comp3220.ecs.soton.ac.uk/sites/4",
									    "rooms": "http://comp3220.ecs.soton.ac.uk/buildings/200/rooms"
									}

Update building information

PUT http://comp3220.ecs.soton.ac.uk/rooms/{building_id}

PATCH http://comp3220.ecs.soton.ac.uk/rooms/{building_id}

There are two methods that can be used to update the information for a building: PUT and PATCH. PUT requires all of the information stated in the Request Fields to be present, while PATCH does not require all of stated fields. In both cases, the format for Parameters, Request Fields and Response Fields are the same.

Parameters

Name Type Location Description
building_id integer URL Unique id for a room
Authorization string Header Client's authorization token

Request Fields *

Field Type Description
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building
site string URL for the site in which this building is located in
*The request fields are mandatory for PUT requests only.

Response Fields

The response will be a list of rooms, each with the following fields:

Field Type Description
url string URL for this building
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building
site string URL for the site in which this building is located in
rooms string URL for the list of rooms located in this building

Example Request

PUT/PATCH http://comp3220.ecs.soton.ac.uk/buildings/190

									{
									    "name": "550 Burgess Road",
									    "number": "550",
									    "latitude": "15.670",
									    "longitude": "-11.345",
									    "site": "http://comp3220.ecs.soton.ac.uk/sites/4"
									}

Example Response

200 OK

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/buildings/190",
									    "name": "550 Burgess Road",
									    "number": "550",
									    "latitude": "15.670",
									    "longitude": "-11.345",
									    "site": "http://comp3220.ecs.soton.ac.uk/sites/4",
									    "rooms": "http://comp3220.ecs.soton.ac.uk/buildings/190/rooms"
									}

Remove building

DELETE http://comp3220.ecs.soton.ac.uk/buildings/{buildings_id}

Remove a building

Parameters

Name Type Location Description
building_id integer URL Unique id for this building
Authorization string Header Client's authorization token

Example Request

DELETE http://comp3220.ecs.soton.ac.uk/buildings/190

Example Response

204 No Content

Sites

Get site

GET http://comp3220.ecs.soton.ac.uk/sites/{site_id}

Retrieve the information about a site

Parameters

Parameters Type Location Description
site_id integer URL Unique id for a site

Response Fields

Field Type Description
url string URL for this site
number string Identifier for this site
name string Name of this site
buildings string URL for the list of buildings located in this site

Example Request

GET http://comp3220.ecs.soton.ac.uk/sites/4

Example Response

200 OK

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/sites/4",
									    "number": "1",
									    "name": "Highfield Campus",
									    "buildings": "http://comp3220.ecs.soton.ac.uk/sites/4/buildings"
									}

Get list of sites

GET http://comp3220.ecs.soton.ac.uk/sites/

Retrieve the information of all sites

Response Fields

The response will be a list of sites, each with the following fields:

Field Type Description
url string URL for this site
number string Identifier for this site
name string Name of this site
buildings string URL for the list of buildings located in this site

Example Request

GET http://comp3220.ecs.soton.ac.uk/sites

Example Response

200 OK

									[
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/sites/1",
									        "number": "4",
									        "name": "Winchester School of Art",
									        "buildings": "http://comp3220.ecs.soton.ac.uk/sites/1/buildings"
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/sites/2",
									        "number": "5",
									        "name": "The University of Southampton Science Park",
									        "buildings": "http://comp3220.ecs.soton.ac.uk/sites/2/buildings"
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/sites/3",
									        "number": "6",
									        "name": "National Oceanography Centre Campus",
									        "buildings": "http://comp3220.ecs.soton.ac.uk/sites/3/buildings"
									    },

									    ...
									]

Get list of buildings in a site

GET http://comp3220.ecs.soton.ac.uk/sites/{site_id}/buildings

Returns the list of buildings located within a specific site

Parameters

Name Type Location Description
site_id integer URL Unique id for a site

Response Fields

The response will be a list of buildings, each with the following fields:

Field Type Description
url string URL for this building
name string Name of the building
number string Identifier for this building
latitude decimal Latitude of this building
longitude decimal Longitude of this building

Example Request

GET http://comp3220.ecs.soton.ac.uk/sites/1/buildings

Example Response

200 OK

									[
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/buildings/77",
									        "name": "Winchester Temporary Facility",
									        "number": "63P",
									        "latitude": "51.065",
									        "longitude": "-1.309"
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/buildings/79",
									        "name": "WSA Cycle store",
									        "number": "63Z",
									        "latitude": "51.065",
									        "longitude": "-1.309"
									    },
									    {
									        "url": "http://comp3220.ecs.soton.ac.uk/buildings/80",
									        "name": "East Side",
									        "number": "63A",
									        "latitude": "51.066",
									        "longitude": "-1.309"
									    },

									    ...
									]

Create new site

POST http://comp3220.ecs.soton.ac.uk/sites/

Creates a new site

Parameters

Name Type Location Description
Authorization string Header Client's authorization token

Request Fields

Field Type Description
number string Identifier for this site
name string Name of this site

Response Fields

Field Type Description
url string URL for this site
number string Identifier for this site
name string Name of this site
buildings string URL for the list of buildings located in this site

Example Request

POST http://comp3220.ecs.soton.ac.uk/sites/

									{
									    "number": "360",
									    "name": "360 Laboratory",
									}

Example Response

201 Created

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/sites/15",
									    "number": "360",
									    "name": "360 Laboratory",
									    "buildings": "http://comp3220.ecs.soton.ac.uk/sites/15/buildings"
									}

Update site information

PUT http://comp3220.ecs.soton.ac.uk/sites/{site_id}

PATCH http://comp3220.ecs.soton.ac.uk/sites/{site_id}

There are two methods that can be used to update the information for a site: PUT and PATCH. PUT requires all of the information stated in the Request Fields to be present, while PATCH does not require all of stated fields. In both cases, the format for Parameters, Request Fields and Response Fields are the same.

Parameters

Parameters Type Location Description
site_id integer URL Unique id for a site
Authorization string Header Client's authorization token

Request Fields *

Field Type Description
number string Identifier for this site
name string Name of this site
*The request fields are mandatory for PUT requests only.

Response Fields

The response will be a list of sites, each with the following fields:

Field Type Description
url string URL for this site
number string Identifier for this site
name string Name of this site
buildings string URL for the list of buildings located in this site

Example Request

PUT/PATCH http://comp3220.ecs.soton.ac.uk/sites/15

									{
									    "number": 361,
									    "name": "361 Laboratory"
									}

Example Response

200 OK

									{
									    "url": "http://comp3220.ecs.soton.ac.uk/sites/15",
									    "number": "361",
									    "name": "361 Laboratory",
									    "buildings": "http://comp3220.ecs.soton.ac.uk/sites/15/buildings"
									}

Delete site

DELETE http://comp3220.ecs.soton.ac.uk/sites/{site_id}

Delete a site

Parameters

Parameter Type Location Description
Authorization string Header Client's authorization token
site_id integer URL Unique id for this site

Example Request

DELETE http://comp3220.ecs.soton.ac.uk/sites/15

Example Response

204 No Content

Miscellaneous

Accepted Content Types

For each type of resource (room, building or site), the content type for both the request and response fields are the same: application/xml, application/json for parsing at the server side, and application/xml, application/json, text/csv for rendering at the client side.

The following API endpoints can be used as a reference to obtain the accepted content types (for parsing and rendering) for the different type of resources.

  • OPTION http://comp3220.ecs.soton.ac.uk/rooms/
  • OPTION http://comp3220.ecs.soton.ac.uk/rooms/{room_id}
  • OPTION http://comp3220.ecs.soton.ac.uk/buildings/
  • OPTION http://comp3220.ecs.soton.ac.uk/buildings/{building_id}
  • OPTION http://comp3220.ecs.soton.ac.uk/buildings/{building_id}/rooms
  • OPTION http://comp3220.ecs.soton.ac.uk/sites
  • OPTION http://comp3220.ecs.soton.ac.uk/sites/{site_id}
  • OPTION http://comp3220.ecs.soton.ac.uk/buildings/{site_id}/buildings

Details on updating resources

The following API endpoints can be used as a reference to obtain further constraints about the request fields that the client needs to conform to while sending PUT or PATCH requests to the server.

Buildings

  • OPTION http://comp3220.ecs.soton.ac.uk/buildings/
  • OPTION http://comp3220.ecs.soton.ac.uk/buildings/{building_id}

Sites

  • OPTION http://comp3220.ecs.soton.ac.uk/sites/
  • OPTION http://comp3220.ecs.soton.ac.uk/sites/{site_id}

Debugging Errors

400 Bad Request

This error occurs while there is an incomplete Request Fields or an invalid Request Fields where the field type, field value or format of the Request Fields is invalid. This applies to POST, PUT or PATCH requests when updating a resource.

Incomplete Request Fields

Check the response body where it describes the required fields, and add any missing fields yo your request body.

Example Request

POST http://comp3220.ecs.soton.ac.uk/rooms

								{
								    "number": "200-3220"
								    "building": "http://comp3220.ecs.soton.ac.uk/buildings/187"
								    [missing capacity],
								    [missing description]
								}

Example Response

400 Bad Request

								{
								    "capacity": [
								        "This field is required."
								    ],
								    "description": [
								        "This field is required."
								    ]
								}

Invalid Request Fields

Check the Request Fields for the relevant endpoint where it describes the types and values of the request fields, and the format of the Request Fields needed. Ensure that your Request Fields conforms to the format described in the relevant endpoint

Example Request

POST http://comp3220.ecs.soton.ac.uk/rooms

								{
								    "number": "200-3220"
								    "description": "CLS for ECS students",
								    "building": 24, [building should be a URL string]
								    "capacity": 44.6 [capacity should be an integer]
								}

Example Response

400 Bad Request

								{
								    "building": [
								        "Incorrect type. Expected URL string, received int."
								    ],
								    "capacity": [
								        "A valid integer is required."
								    ]
								
							}

401 Unauthorized

This error occurs when there is a missing authorization token in the request headers when performing requests changes the state of a given resource such as POST, PUT, PATCH and DELETE. To fix this, simply add the authorization token in the header when creating, updating or deleting a resource:

Authorization: Token <token_id>

Example Response

401 Unauthorized

								{
								    "detail": "Authentication credentials were not provided."
								}

404 Not Found

This error occurs when the requested resource does not exist. Ensure that the resource requested exists within the server.

Example Request

 GET http://comp3220.ecs.soton.ac.uk/rooms/800 [room_id of 800 does not exist]

Example Response

404 Not Found

							{
							    "detail": "Not Found."
							}

405 Method Not Allowed

This error occurs when the URL template for a request action on a specific endpoint is invalid. Ensure that all required URL parameters are provided for PUT, PATCH and DELETE requests.

Example Request

{
							    DELETE http://comp3220.ecs.soton.ac.uk/rooms/[missing room_id]
							}

Example Response

{
							    "detail": "Method \"DELETE\" not allowed."
							}