Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/danpalmer/comp6017

Advanced Topics on Web Services
https://github.com/danpalmer/comp6017

Last synced: 25 days ago
JSON representation

Advanced Topics on Web Services

Host: GitHub
URL: https://github.com/danpalmer/comp6017
Owner: danpalmer
Created: 2013-11-23T16:14:35.000Z (almost 11 years ago)
Default Branch: master
Last Pushed: 2013-12-16T21:17:40.000Z (almost 11 years ago)
Last Synced: 2024-04-08T16:59:40.353Z (7 months ago)
Language: JavaScript
Size: 465 KB
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# COMP6017 -- Advanced Topics on Web Service

### API Endpoints

All endpoints return `application/javascript` unless otherwise stated. All endpoints will respond to the **HEAD** method with the appropriate headers, and **OPTIONS** with the available methods for a given endpoint.

##### /
- **GET**: if the request header specifies `Accept: application/json` (or the HAL variant), then this returns the valid links formatted in JSON HAL, otherwise this returns the README formatted as `text/html`.

##### /user
- **GET**: returns a list of users.
- **POST**: creates and returns a user.

##### /user/:uid
- **GET**: returns the specified user.
- **PUT**: updates and returns the specified user.
- **DELETE**: deletes the specified user.

##### /question
- **GET**: returns a list of questions.
- **POST**: creates and returns a question.

##### /question/:qid
- **GET**: returns the specified question.
- **PUT**: updates and returns the specified user.
- **DELETE**: deletes the specified question.

##### /question/:qid/comment
- **GET**: returns a list of comments for the specified question.
- **POST**: creates and returns a comment on the specified question.

##### /question/:qid/comment/:cid
- **GET**: returns the specified comment for the specified question.
- **PUT**: updates returns the specified comment for the specified question.
- **DELETE**: deletes the specified comment for the specified question.

##### /question/:qid/answer
- **GET**: returns a list of answers for the specified question.
- **POST**: creates and returns an answer on the specified question.

##### /question/:qid/answer/:aid
- **GET**: returns the specified answer for the specified question.
- **PUT**: updates returns the specified answer for the specified question.
- **DELETE**: deletes the specified answer for the specified question.

##### /question/:qid/answer/:aid/comment
- **GET**: returns a list of comments for the specified answer on the specified question.
- **POST**: creates and returns a comment on the specified answers on the specified question.

##### /question/:qid/answer/:aid/comment/:cid
- **GET**: returns the specified comment for the specified answer on the specified question.
- **PUT**: updates returns the specified comment for the specified answer on the specified question.
- **DELETE**: deletes the specified comment for the specified answer on the specified question.

##### URL Parameter Names:

- `:uid` - User Id
- `:qid` - Question Id
- `:cid` - Comment Id
- `:aid` - Answer Id

### Data Models

##### User

User Provided Fields:

- **name**: String, Editable, Required.
- **email**: String (valid email address), Editable, Required.

Extra Returned Fields:

- **dateSignedUp**: Date, Read-Only.
- **dateModified**: Date, Read-Only.

##### Question

User Provided Fields:

- **title**: String, Editable, Required.
- **content**: String, Editable, Required.
- **author_id**: Number (author ID), Required.

Extra Returned Fields:

- **dateCreated**: Date, Read-Only.
- **dateModified**: Date, Read-Only.

Linked/Embedded Resources:

- **author**: User.
- **comments**: List of Comments
- **answers**: List of Answers

##### Answer

User Provided Fields:

- **content**: String, Editable, Required.
- **author_id**: Number (author ID), Required.

Extra Returned Fields:

- **dateCreated**: Date, Read-Only.
- **dateModified**: Date, Read-Only.

Linked/Embedded Resources:

- **question**: Question.
- **author**: User.
- **comments**: List of Comments

##### Comment

User Provided Fields:

- **content**: String, Editable, Required.
- **author_id**: Number (author ID), Required.

Extra Returned Fields:

- **dateCreated**: Date, Read-Only.
- **dateModified**: Date, Read-Only.

Linked/Embedded Resources:

- **parent**: Question/Answer.
- **author**: User.

### Design Decisions

##### HTTP Status Codes

- Successful: 200 OK
- Created server-side representation (on POST): 201 Created
- Deleted server-side representation (on DELETE): 204 No Content
- Updated server-side representation (on PUT): 200 OK
- Failed to store representation: 503 Service Unavailable
- Failed to find resource: 404 Not Found
- Failed to delete resource: 503 Service Unavailable
- POST doesn't contain required fields: 400 Bad Request
- PUT doesn't contain required fields: 400 Bad Request
- POST contains invalid field (e.g. non-existent question for comment): 400 Bad Request

##### HATEOAS

We have made the decision to implement [JSON HAL (Hypertext Application Language)](http://tools.ietf.org/html/draft-kelly-json-hal-06). Linked resources are included in the `_links` object, where keys are the relation name, and values are an object with an `href` link to the resource. Aternatively, resources can be included directly in the `_embedded` object, where keys are the relation name, and values are the representation of that resource.

Here is a single question from a list of questions given by `/question` as an example of the usage of `_links`:
```json
{
title: "Test Question",
content: "Lorem ipsum dolor sit amet.",
dateCreated: "2013-12-14T20:06:34.519Z",
dateModified: "2013-12-14T20:06:34.519Z",
id: 6,
_links: {
self: { href: "/question/6" },
author: { href: "/user/6" },
answers: { href: "/question/6/answer" },
comments: { href: "/question/6/comment" }
}
}
```

Here is the same question with included resources, as in `/question/:id` to demonstrate usage of `_embedded`:
```
{
title: "Test Question",
content: "Lorem ipsum dolor sit amet.",
dateCreated: "2013-12-14T20:06:34.519Z",
dateModified: "2013-12-14T20:06:34.519Z",
id: 6,
_links: {
self: { href: "/question/6" }
},
_embedded: {
author: {
name: "Test User",
email: "[email protected]",
dateSignedUp: "2013-12-14T20:06:34.515Z",
dateModified: "2013-12-14T20:06:34.515Z",
id: 6,
_links: {
self: { href: "/user/6" }
}
},
answers: [{
content: "This is a test answer",
dateCreated: "2013-12-15T19:59:14.984Z",
dateModified: "2013-12-15T19:59:14.984Z",
id: 77,
_links: {
self: { href: "/question/6/answer/77" },
comments: { href: "/question/6/answer/77/comment" }
},
_embedded: {
author: {
name: "Test User",
email: "[email protected]",
dateSignedUp: "2013-12-14T20:06:34.414Z",
dateModified: "2013-12-14T20:06:34.414Z",
id: 1,
_links: {
self: { href: "/user/1" }
}
}
}
}],
comments: [{
content: "test content",
dateCreated: "2013-12-14T20:06:34.525Z",
dateModified: "2013-12-14T20:06:34.525Z",
id: 1,
_links: {
self: { href: "/question/6/comment/1" }
},
_embedded: {
author: {
name: "Test User",
email: "[email protected]",
dateSignedUp: "2013-12-14T20:06:34.515Z",
dateModified: "2013-12-14T20:06:34.515Z",
id: 6,
_links: {
self: { href: "/user/6" }
}
}
}
}]
}
}
```

For backwards compatibility with clients who are not JSON HAL aware, and for compatibility with the Express web framework, resources are returned as `application/json` instead of `application/hal+json` as recommended.

### Testing

For testing the service we have created an automated test suite using Mocha -- a Node.js package for writing TDD/BDD style asynchronous tests. Assuming that the npm packages specified in `package.json` are installed to `node_modules`, and assuming the server is running on the default port (3000), tests can be run with the following command:

```
$ node_modules/.bin/mocha -R spec tests
```

This prints out a list of tests and their status, printing stack traces wherever they may fail. As of submission, the tests are all passing. If any failing tests are encountered, ensure the server is running on port 3000, is accessible, that the project directory is writeable for the database creation, and that all modules in `package.json` have successfully installed. If these requirements have been satisfied, contact Dan Palmer and Sam Bull.

### JSLint Compliance

We have complied with JSLint, when run with the following options: `--node --devel --sloppy --unparam --nomen`. The tests are executed within a Mocha environment, which provides the global functions `describe` and `it` (along with others that we have no used), and therefore the tests will only pass JSLint validation with `--predef describe --predef it`.