-
Notifications
You must be signed in to change notification settings - Fork 0
API
RESTful Scheduling System uses the standard HTTP and REST verbs.
| Verb | Usage |
|---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource, including partial updates |
|
Used to delete an existing resource |
RESTful Scheduling System uses the standard HTTP status codes.
| Status code | Usage |
|---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
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 |
|---|---|---|
|
|
The HTTP error that occurred, e.g. |
|
|
A description of the cause of the error |
|
|
The path to which the request was made |
|
|
The HTTP status code, e.g. |
|
|
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"}
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
The index provides the entry point into the service.
A GET request is used to access the index
| Path | Type | Description |
|---|---|---|
|
|
Links to other resources |
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"
}
}
}
| Relation | Description |
|---|---|
|
|
|
The Classes resource |
|
The ALPS profile for the service |
The Students resources is used to create and list students
A GET request will list all of the service’s students.
| Path | Type | Description |
|---|---|---|
|
|
An array of Student resources |
|
|
Links to other resources |
|
|
Contains pagination info |
|
|
Number of students on this page |
|
|
Number of students on this collection |
|
|
Number of pages on this collection |
|
|
Page number |
GET /students HTTP/1.1
Host: localhost:8080HTTP/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
}
}
| Relation | Description |
|---|---|
|
Canonical link for this resource |
|
The ALPS profile for this resource |
|
Link to the search resource |
A POST request is used to create a student
| Path | Type | Description |
|---|---|---|
|
|
The student’s first name |
|
|
The student’s last name |
|
|
An array of class resource URIs |
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"]}
HTTP/1.1 201 Created
Location: http://localhost:8080/students/1A GET request is used to search students
| Parameter | Description |
|---|---|
|
The first name of the students to search |
|
The last name of the students to search |
GET /students/search/search?firstName=ry&lastName=ar HTTP/1.1
Host: localhost:8080HTTP/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&lastName=ar"
}
}
}
The Classes resource is used to create and list classes.
A GET request will list all of the service’s classes.
| Path | Type | Description |
|---|---|---|
|
|
An array of Class resources |
|
|
Links to other resources |
|
|
Contains pagination info |
|
|
Number of classes on this page |
|
|
Number of classes on this collection |
|
|
Number of pages on this collection |
|
|
Page number |
GET /classes HTTP/1.1
Host: localhost:8080HTTP/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
}
}
| Relation | Description |
|---|---|
|
Canonical link for this resource |
|
The ALPS profile for this resource |
|
Link to the search resource |
A POST request is used to create a student
| Path | Type | Description |
|---|---|---|
|
|
The unique code for this class |
|
|
The title of the class |
|
|
The description of the class |
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"}
HTTP/1.1 201 Created
Location: http://localhost:8080/classes/physics-101A GET request is used to search classes
| Parameter | Description |
|---|---|
|
The code of the classes to search |
|
The title of the classes to search |
|
The description of the classes to search |
GET /students/search/search?firstName=ry&lastName=ar HTTP/1.1
Host: localhost:8080HTTP/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&lastName=ar"
}
}
}
The Student resource is used to retrieve, update, and delete individual students
| Relation | Description |
|---|---|
|
Canonical link for this student |
|
This student |
|
This student’s classes |
A GET request will retrieve the details of a student
| Path | Type | Description |
|---|---|---|
|
|
The student’s unique identifier |
|
|
The student’s first name |
|
|
The student’s last name |
|
|
Links to other resources |
|
|
Who created this student |
|
|
The date in which this student was created |
|
|
Who modified this student |
|
|
The date in which this student was modified |
GET /students/3 HTTP/1.1
Host: localhost:8080HTTP/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"
}
}
}
A PATCH request is used to update a student
| Path | Type | Description |
|---|---|---|
|
|
The student’s first name |
|
|
The student’s last name |
|
|
An array of class resource URIs |
To leave an attribute of a student unchanged, any of the above may be omitted from the 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"]}
HTTP/1.1 204 No Content
ETag: "1"
Last-Modified: Mon, 26 Dec 2016 20:16:47 GMTA POST request is used to enroll a student in a class
The request body must be a list of class resource URIs
POST /students/2/classes HTTP/1.1
Content-Type: text/uri-list
Host: localhost:8080
Content-Length: 41
HTTP/1.1 204 No ContentThe Class resource is used to retrieve, update, and delete individual classes
| Relation | Description |
|---|---|
|
Canonical link for this class |
|
This class |
|
The students enrolled in this class |
A GET request will retrieve the details of a class
| Path | Type | Description |
|---|---|---|
|
|
The unique code for this class |
|
|
The title of the class |
|
|
The description of the class |
|
|
Links to other resources |
|
|
Who created this class |
|
|
The date in which this class was created |
|
|
Who modified this class |
|
|
The date in which this class was modified |
GET /classes/physics-101 HTTP/1.1
Host: localhost:8080HTTP/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"
}
}
}
A PATCH request is used to update a class
| Path | Type | Description |
|---|---|---|
|
|
The unique code for this class |
|
|
The title of the class |
|
|
The description of the class |
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"}
HTTP/1.1 204 No Content
ETag: "1"
Last-Modified: Mon, 26 Dec 2016 20:16:47 GMT