Scribd
Upload
97 views

REST

The document provides guidelines for building a single page application with Vue and webpack. It outlines components for user registration, login, payment, signals, and settings. It also includes documentation for the REST API, describing authentication with JSON web tokens, user registration and login endpoints, retrieving historical signals, and a real-time websocket feed for new signals.

Uploaded by

Jason Cipher
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
97 views

REST

The document provides guidelines for building a single page application with Vue and webpack. It outlines components for user registration, login, payment, signals, and settings. It also includes documentation for the REST API, describing authentication with JSON web tokens, user registration and login endpoints, retrieving historical signals, and a real-time websocket feed for new signals.

Uploaded by

Jason Cipher
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 9

Single Page Application Components

All components are very general guidelines. Overall design and aesthetic choices are left to the
discretion of the designer. Refer to the REST API documentation for specific field names,
responses, and URLs. The final web application project should be built with Vue and
obfuscated/optimized with webpack.

Register
User registration page that contains a textbox for the following information:
● Username
● Email address
● Password
● Password verification
● Captcha

Forms should be validated prior to submission. Must not refresh page upon submission.
Seamlessly transfer to main application interface. Display error messages cleanly. Upon
success, redirect to main ​Signals​ page.

Login
User login page that contains a textbox for the following information:
● username
● password
● mfatoken (Hidden at first. Only show upon a 202 response.)
When the user submits his or her credentials, the server does not differentiate between users
not existing and incorrect credentials (to prevent user enumeration). This should be reflected in
the web application. A 202 will be sent indicating that the MFA token field should be visible.

Payment
Payment page that displays information on the various subscriptions plans. Just contains links
to the selly application as well as displaying the username.

Signals
Should immediately query for existing signals via the REST API once the component loads and
display them cleanly in a table in descending order of when they were received (Newest First).
The websocket connection should also take place within this component. Any new item sent
over the websocket should be added to the displayed table. It should be obvious that a new
signal has been generated (flash of highlighted color, bell sound, etc)

Settings
There is currently little server-side functionality for saving user settings.
Rest API Documentation

Authentication
All authentication uses JSON Web Tokens. Each request (after authentication) requires an
authorization header in the form of:

Authorization: Bearer xxx.xxx.xxx

Where xxx.xxx.xxx is the JWT token value. The JWT is comprised of three parts, separated by a
period delimiter. ​Note:​ Base64 data used is escaped with non-default characters to make them
URL safe (“-” and “_” replace “+” and “/” respectively). In JavaScript, I used the following
function as a getter for a VueX store:

jwt_data: state => {


if (state.jwt === '') {
return {}
}
var base64Url = state.jwt.split('.')[1]
var base64 = base64Url.replace('-', '+').replace('_', '/')
return JSON.parse(window.atob(base64))
}

Any further reference to “Base64 encoding” pertaining to the JWT will assume this URL
escaped modified function.
JWT Token Layout

Three parts of the JWT


1. Base64 encoded JSON structure defining the algorithm used. Contains no pertinent
application data. ​No need for processing in web app.
2. Base64 encoded JSON structure containing all necessary application data. Example
below.
3. Base64 encoded SHA256 hash. Cryptographic signature of the data to ensure it has not
been modified by the user. ​No need for processing in web app.
{
"uid": "f0c6bd2ae9c04bd8bfae2a1140a85b61",
"sip": "127.0.0.1",
"admin": true,
"sub_exp": 1526145331,
"iss": "localhost",
"iat": 1523553335,
"exp": 1523553635
}

uid User’s unique ID.

sip Source IP address of the initial authentication request. Tokens cannot be


generated from a new source IP. Tokens sent from a different IP will result in
a 403 forbidden error.

admin Determines if a user account is an admin or not.

sub_exp UTC Timestamp of when the subscription is set to expire.

iss Issuer of the token (set to our domain name).

iat The integer timestamp of when the token was issued.

exp The integer timestamp of when the token expires.


User Registration
http://api.example.com/v1/register

POST

Request JSON Parameters


● username desired username
● email desired email address
● password desired plaintext password

Constraints
● username regex:
^[a-zA-Z][a-zA-Z0-9_\-\.]{2,14}$
● email regex:
^(([^<>()\[\]\\.,;:\s@\"]+(\.[^<>()\[\]\\.,;:\s@\"]+)*)|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[
0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$

Response Parameters
● success Always given. Boolean value.
● message Always given. String/status message.
● fields Given with 422. List of strings containing the names of fields with
invalid values.

Response Status Codes


● 406 Invalid JSON
● 422 Invalid/Missing parameters
● 409 Username/Email Unavailable
● 201 User Created
User Authentication
http://api.example.com/v1/login

Authenticates the user. Web app should display a username/password prompt. It should display
a 2FA token ONLY when a 422 status code is returned. The HTTP response will contain an
Authorization Bearer token. This token must be used for all subsequent requests.

POST

Request JSON Parameters


● username Required. Authentication username
● password Required. Authentication password
● mfatoken Optional. Multi-factor authentication token

Response JSON Parameters


● success Always given. Boolean value.
● message Always given. String/status message.
● token Given on 200. New auth token.
● field Given on 400 status codes. Determines which submitted field has the
issue. Can be used for auto-focus in the web app.

Response Status Codes


● 406 Invalid JSON
● 429 Exceeded rate limit.
● 403 Incorrect username/password
● 401 Multi-factor token is incorrect.
● 403 Account is disabled.
● 202 Login correct but multi-factor required but not provided
● 200 Login successful
Signals
http://api.example.com/v1/signals

Retrieves the historical signals from the database.

GET
● JWT token required via Authorization HTTP header.

Response JSON Parameters


● success Always given. Boolean value.
● message Always given. String/status message.
● token Given on 200 status. New auth token.
● signals Given on 200 status. List of signals in the following JSON format:
○ id Unique ID of the signal.
○ signal String containing the signal message.
○ channel String containing the channel name.
○ received UTC integer timestamp of when it was added.

Response Status Codes


● 401 Invalid/No token
● 402 Subscription has expired
● 403 source IP changed
● 200 signals returned successfully

POST
● Authentication token ​NOT​ required. API key used instead for stateless/sessionless
authentication. Not required to be submitted via the web app. 3rd party libraries/tools will
be used.
Signal Websocket Feed
ws://api.example.com/v1/signals/feed

Real-time signals sending over a websocket.

1. On connection to the websocket, submit JSON data as follows:


{
“access_token”: “<JWT authentication token>”
}
2. Every 60 seconds or so, the websocket will send a new token in an identical form:
{
“Success”: true,
“access_token”: “<New JWT authentication token>”
}
3. Whenever a new signal is submitted/generated, it is sent over the websocket WITHOUT
a token parameter. Layout:
{
"success": true,
"signal": "This is a test signal",
"channel": "Channel Name",
"received": 1523555579
}
Example websocket communications:

Websocket will automatically close if the subscription expires. Here’s an example of it expiring
during a connection:

You might also like

pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy