This repository contains a Node.js / Express / Angularjs simple webapp for a chat.
It can be used as a nice learning API.
Source code is available and released under the Apache 2.0 License.
The API has been developed in multiple versions:
- 1.0: Easiest to implement. Registration is done via an HTML page or via path variables, messages can be fetched with path variables.
- 2.0: Harder to implement, but more secure. Login is done via basic HTTP, messages can contain attachments, can be fetched only with basic auth headers, and supports pagination.
The URI is formed of three parts: {baseURL}/{versionPrefix}/{route}
An example instance was published on the following baseURL: http://training.loicortola.com/chat-rest
versionPrefix: 1.0
This API has permissive request Content-Types, and is best fit for beginners.
| Endpoint | Returns | | ----- | ------ | ----------- | ------- | |
- Route:
/register/{login}/{password} - Method:
POST - Description: Register new user to chat service through API
| Status | Body |
|---|---|
| 200-OK | JSON response {"status":200,"message":"Registered successfully"} if everything went well. |
| 400-BAD-REQUEST | with JSON response {"status":400,"message":"...","elements":"..."} if login or/and password already exist |
- Route:
/connect/{login}/{password} - Method:
GET - Description: Connect new user to chat service through API
| Status | Body |
|---|---|
| 200-OK | JSON response {"status":200,"message":"Login successful"} if everything went well. |
| 401-UNAUTHORIZED | with JSON response {"status":401,"message":"...","elements":"..."} if login or/and password provided are not correct |
- Route:
/messages/{login}/{password} - Method:
GET - Description: Retrieve all messages from chat service API
| Status | Body |
|---|---|
| 200-OK | JSON Array response [{"uuid":"...","login":"john","message":"Hello world! Ping"},{"uuid":"...","login":"jane","message":"Pong!"}] if everything went well. |
| 401-UNAUTHORIZED | with JSON response {"status":401,"message":"...","elements":"..."} if login or/and password provided are not correct |
- Route:
/messages/{login}/{password} - Method:
POST - Post new message to chat service API
Request body: {"uuid":"...","login":"jane","message":"Pong!"}
Warning: uuid is mandatory and should be a valid generated uuid!
| Status | Body |
|---|---|
| 200-OK | JSON response {"status":200,"message":"Message posted successfully"} if everything went well. |
| 400-BAD-REQUEST | with JSON response {"status":400,"message":"...","elements":"..."} if any mandatory body fields are absent/invalid or if message has already been posted. |
| 401-UNAUTHORIZED | with JSON response {"status":401,"message":"...","elements":"..."} if login or/and password provided are not correct |
versionPrefix: 2.0
This API performs authentication using basic authentication (more info: https://en.wikipedia.org/wiki/Basic_access_authentication)
The API searches for Content-Type:application/json header when required, and is best fit for advanced use.
| Endpoint | Returns | | ----- | ------ | ----------- | ------- | |
- Route:
/register - Method:
POST - Description: Register new user to chat service through API
Request body: {"login":"foo","password":"bar"}
Warning: requires Content-Type:application/json header!
| Status | Body |
|---|---|
| 200-OK | JSON response {"status":200,"message":"Registered successfully"} if everything went well. |
| 400-BAD-REQUEST | with JSON response {"status":400,"message":"...","elements":"..."} if login or/and password already exist, or fields not properly set. |
- Route:
/connect - Method:
GET - Description: Connect new user to chat service through API
Warning: requires Basic Authentication!
| Status | Body |
|---|---|
| 200-OK | JSON response {"status":200,"message":"Login successful"} if everything went well. |
| 401-UNAUTHORIZED | with JSON response {"status":401,"message":"...","elements":"..."} if login or/and password provided are not correct |
- Route:
/messages?&limit=10&offset=20 - Method:
GET - Description: Retrieve all messages from chat service API
Optional parameters:
limit: maximum number of results.
offset: result offset.
Warning: requires Basic Authentication!
| Status | Body |
|---|---|
| 200-OK | JSON Array response [{"uuid":"...","login":"john","message":"Hello world! Ping"},{"uuid":"...","login":"jane","message":"Pong!", "images": ["http://training.loicortola.com/2.0/files/.../1.png"]}] if everything went well. NB: images is not a mandatory field. it can hold URLs to the image attachments posted along with a message. |
| 401-UNAUTHORIZED | with JSON response {"status":401,"message":"...","elements":"..."} if login or/and password provided are not correct |
- Route:
/messages - Method:
POST - Post new message to chat service API
Warning: requires Basic Authentication!
Request body: {"uuid":"...","login":"jane","message":"Pong!", "attachments": [{"mimeType": "image/png", "data": "yourbase64imagecontenthere"}]}
Warning: uuid is mandatory and should be a valid generated uuid!
NB: attachments is not a mandatory field. it can hold image/png or image/jpg content. Warning, size is limited to 1024kb by default.
| Status | Body |
|---|---|
| 200-OK | JSON response {"status":200,"message":"Message posted successfully"} if everything went well. |
| 400-BAD-REQUEST | with JSON response {"status":400,"message":"...","elements":"..."} if any mandatory body fields are absent/invalid or if message has already been posted. |
| 401-UNAUTHORIZED | with JSON response {"status":401,"message":"...","elements":"..."} if login or/and password provided are not correct |
- Route:
/files/{uuid}/{fileName} - Method:
GET - Description: Retrieve file posted along depending on the file extension.
| Status | Body |
|---|---|
| 200-OK | image/* response if everything went well. |
| 404-NOT-FOUND | if image does not exist. |
Besides the API, the Chat system has an HTML registration page available at route /
Administrators can monitor activity with the HTML dashboard, and reset memory at /dashboard (requires admin login).
The source code is now released along with the API description.
Please update the configuration with your own in conf/conf.js
Requirements: node, npm
Execute the following commands:
npm install
bower install
gulp
./start.sh
Copyright 2015 Loïc Ortola
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.