RESTful Scheduling System API Guide

Table of Contents

Overview
Resources

Overview

HTTP verbs

RESTful Scheduling System uses the standard HTTP and REST verbs.

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

HTTP status codes

RESTful Scheduling System uses the standard HTTP status codes.

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 did not exist

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
`error`	`String`	The HTTP error that occurred, e.g. `Bad Request`
`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`	`String`	The time, in milliseconds, at which the error occurred

For example, a request that attempts to assign a non-existent class to a student will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 174
{"timestamp":"2016-12-26T20:16:47.451+0000","status":400,"error":"Bad Request","message":"The student 'http://localhost:8080/students/123' does not exist","path":"/students"}

Hypermedia

RESTful Scheduling System 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

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 339
{
"_links" : {
"classes" : {
"href" : "http://localhost:8080/classes{?page,size,sort}",
"templated" : true
},
"students" : {
"href" : "http://localhost:8080/students{?page,size,sort}",
"templated" : true
},
"profile" : {
"href" : "http://localhost:8080/profile"
}
}
}

Links

Relation	Description
`students`	The Students resource
`classes`	The Classes resource
`profile`	The ALPS profile for the service

Path	Type	Description
`_embedded.students`	`Array`	An array of Student resources
`_links`	`Object`	Links to other resources
`page`	`Object`	Contains pagination info
`page.size`	`Number`	Number of students on this page
`page.size`	`Number`	Number of students on this collection
`page.size`	`Number`	Number of pages on this collection
`page.size`	`Number`	Page number

Example request

GET /students HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2048
{
"_embedded" : {
"students" : [ {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.306Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.306Z",
"id" : 6,
"firstName" : "Robb",
"lastName" : "Stark",
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/6"
},
"student" : {
"href" : "http://localhost:8080/students/6"
},
"classes" : {
"href" : "http://localhost:8080/students/6/classes"
}
}
}, {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.31Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.31Z",
"id" : 7,
"firstName" : "Jon",
"lastName" : "Snow",
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/7"
},
"student" : {
"href" : "http://localhost:8080/students/7"
},
"classes" : {
"href" : "http://localhost:8080/students/7/classes"
}
}
}, {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.321Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.321Z",
"id" : 8,
"firstName" : "Bran",
"lastName" : "Stark",
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/8"
},
"student" : {
"href" : "http://localhost:8080/students/8"
},
"classes" : {
"href" : "http://localhost:8080/students/8/classes"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/students"
},
"profile" : {
"href" : "http://localhost:8080/profile/students"
},
"search" : {
"href" : "http://localhost:8080/students/search"
}
},
"page" : {
"size" : 20,
"totalElements" : 3,
"totalPages" : 1,
"number" : 0
}
}

Links

Relation	Description
`self`	Canonical link for this resource
`profile`	The ALPS profile for this resource
`search`	Link to the search resource

Creating a student

A POST request is used to create a student

Request structure

Path	Type	Description
`firstName`	`String`	The student’s first name
`lastName`	`String`	The student’s last name
`classes`	`Array`	An array of class resource URIs

Example request

POST /students HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080
Content-Length: 93
{"firstName":"Jon","lastName":"Snow","classes":["http://localhost:8080/classes/physics-101"]}

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/students/1

Searching students

A GET request is used to search students

Request parameters structure

Parameter	Description
`firstName`	The first name of the students to search
`lastName`	The last name of the students to search

Example request

GET /students/search/search?firstName=ry&lastName=ar HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 728
{
"_embedded" : {
"students" : [ {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:46.843Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:46.843Z",
"id" : 4,
"firstName" : "Arya",
"lastName" : "Stark",
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/4"
},
"student" : {
"href" : "http://localhost:8080/students/4"
},
"classes" : {
"href" : "http://localhost:8080/students/4/classes"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/search/search?firstName=ry&amp;lastName=ar"
}
}
}

Path	Type	Description
`_embedded.classes`	`Array`	An array of Class resources
`_links`	`Object`	Links to other resources
`page`	`Object`	Contains pagination info
`page.size`	`Number`	Number of classes on this page
`page.size`	`Number`	Number of classes on this collection
`page.size`	`Number`	Number of pages on this collection
`page.size`	`Number`	Page number

Example request

GET /classes HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2258
{
"_embedded" : {
"classes" : [ {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.185Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.185Z",
"code" : "algebra-1O1",
"title" : "Algebra 101",
"description" : "Description of Algebra 101",
"_links" : {
"self" : {
"href" : "http://localhost:8080/classes/algebra-1O1"
},
"class" : {
"href" : "http://localhost:8080/classes/algebra-1O1"
},
"students" : {
"href" : "http://localhost:8080/classes/algebra-1O1/students"
}
}
}, {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.182Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.182Z",
"code" : "calculus-1O1",
"title" : "Calculus 101",
"description" : "Description of Calculus 101",
"_links" : {
"self" : {
"href" : "http://localhost:8080/classes/calculus-1O1"
},
"class" : {
"href" : "http://localhost:8080/classes/calculus-1O1"
},
"students" : {
"href" : "http://localhost:8080/classes/calculus-1O1/students"
}
}
}, {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.177Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.177Z",
"code" : "physics-1O1",
"title" : "Physics 101",
"description" : "Description of Physics 101",
"_links" : {
"self" : {
"href" : "http://localhost:8080/classes/physics-1O1"
},
"class" : {
"href" : "http://localhost:8080/classes/physics-1O1"
},
"students" : {
"href" : "http://localhost:8080/classes/physics-1O1/students"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/classes"
},
"profile" : {
"href" : "http://localhost:8080/profile/classes"
},
"search" : {
"href" : "http://localhost:8080/classes/search"
}
},
"page" : {
"size" : 20,
"totalElements" : 3,
"totalPages" : 1,
"number" : 0
}
}

Links

Relation	Description
`self`	Canonical link for this resource
`profile`	The ALPS profile for this resource
`search`	Link to the search resource

Creating a class

A POST request is used to create a student

Request structure

Path	Type	Description
`code`	`String`	The unique code for this class
`title`	`String`	The title of the class
`description`	`String`	The description of the class

Example request

POST /classes HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080
Content-Length: 87
{"code":"physics-101","description":"Description of Physics 101","title":"Physics 101"}

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/classes/physics-101

Searching classes

A GET request is used to search classes

Request parameters structure

Parameter	Description
`code`	The code of the classes to search
`title`	The title of the classes to search
`description`	The description of the classes to search

Example request

GET /students/search/search?firstName=ry&lastName=ar HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 728
{
"_embedded" : {
"students" : [ {
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:46.843Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:46.843Z",
"id" : 4,
"firstName" : "Arya",
"lastName" : "Stark",
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/4"
},
"student" : {
"href" : "http://localhost:8080/students/4"
},
"classes" : {
"href" : "http://localhost:8080/students/4/classes"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/search/search?firstName=ry&amp;lastName=ar"
}
}
}

Student

The Student resource is used to retrieve, update, and delete individual students

Links

Relation	Description
`self`	Canonical link for this student
`student`	This student
`classes`	This student’s classes

Retrieve a student

A GET request will retrieve the details of a student

Response structure

Path	Type	Description
`id`	`Number`	The student’s unique identifier
`firstName`	`String`	The student’s first name
`lastName`	`String`	The student’s last name
`_links`	`Object`	Links to other resources
`createdBy`	`Null`	Who created this student
`createdDate`	`String`	The date in which this student was created
`modifiedBy`	`Null`	Who modified this student
`modifiedDate`	`String`	The date in which this student was modified

Example request

GET /students/3 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Last-Modified: Mon, 26 Dec 2016 20:16:46 GMT
ETag: "0"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 466
{
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:46.532Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:46.532Z",
"id" : 3,
"firstName" : "Jon",
"lastName" : "Snow",
"_links" : {
"self" : {
"href" : "http://localhost:8080/students/3"
},
"student" : {
"href" : "http://localhost:8080/students/3"
},
"classes" : {
"href" : "http://localhost:8080/students/3/classes"
}
}
}

Update a student

A PATCH request is used to update a student

Request structure

Path	Type	Description
`firstName`	`String`	The student’s first name
`lastName`	`String`	The student’s last name
`classes`	`Array`	An array of class resource URIs

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

Example request

PATCH /students/5 HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080
Content-Length: 95
{"firstName":"Arya","lastName":"Stark","classes":["http://localhost:8080/classes/physics-101"]}

Example response

HTTP/1.1 204 No Content
ETag: "1"
Last-Modified: Mon, 26 Dec 2016 20:16:47 GMT

POST /students/2/classes HTTP/1.1
Content-Type: text/uri-list
Host: localhost:8080
Content-Length: 41
http://localhost:8080/classes/algebra-101

Example response

HTTP/1.1 204 No Content

Class

The Class resource is used to retrieve, update, and delete individual classes

Links

Relation	Description
`self`	Canonical link for this class
`class`	This class
`students`	The students enrolled in this class

Retrieve a class

A GET request will retrieve the details of a class

Response structure

Path	Type	Description
`code`	`String`	The unique code for this class
`title`	`String`	The title of the class
`description`	`String`	The description of the class
`_links`	`Object`	Links to other resources
`createdBy`	`Null`	Who created this class
`createdDate`	`String`	The date in which this class was created
`modifiedBy`	`Null`	Who modified this class
`modifiedDate`	`String`	The date in which this class was modified

Example request

GET /classes/physics-101 HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Last-Modified: Mon, 26 Dec 2016 20:16:47 GMT
ETag: "0"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 536
{
"createdBy" : null,
"createdDate" : "2016-12-26T20:16:47.547Z",
"modifiedBy" : null,
"modifiedDate" : "2016-12-26T20:16:47.547Z",
"code" : "physics-101",
"title" : "Physics 101",
"description" : "Description of Physics 101",
"_links" : {
"self" : {
"href" : "http://localhost:8080/classes/physics-101"
},
"class" : {
"href" : "http://localhost:8080/classes/physics-101"
},
"students" : {
"href" : "http://localhost:8080/classes/physics-101/students"
}
}
}

Update a class

A PATCH request is used to update a class

Request structure

Path	Type	Description
`code`	`String`	The unique code for this class
`title`	`String`	The title of the class
`description`	`String`	The description of the class

Example request

PATCH /classes/physics-101 HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080
Content-Length: 87
{"code":"algebra-101","description":"Description of Algebra 101","title":"Algebra 101"}

Example response

HTTP/1.1 204 No Content
ETag: "1"
Last-Modified: Mon, 26 Dec 2016 20:16:47 GMT

Last updated 2016-12-26 04:41:25 BOT

API - maikomr/scheduling-system GitHub Wiki

RESTful Scheduling System API Guide

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️