Skip to content

Latest commit

 

History

History
127 lines (82 loc) · 4.98 KB

wip.md

File metadata and controls

127 lines (82 loc) · 4.98 KB
Raw

REST HTTP methods overview

  • GET: retrieve an object or a collection of objects
  • PUT: create or update (overwrite) an object in the collection, the object is placed at the exact place in the provided URI, with the exact MongoID provided, except if it violate uniqness, if an object exists, it is replaced entirely by the new object. Also some PUT method can be rejected if the object already exists, thus favorising the usage of PATCH
  • PATCH: update partially, update only parts of the object present in the patch body
  • DELETE: delete the object (or the collection, if possible)
  • POST:
    • create an object on the collection
    • execute a methods of an entity, e.g. POST /Users/{ID}/Auth will authenticate the user with {ID} as ID, here Auth is not an object or a property, it's a method of the user's object
    • POST always indicate something that cannot be done offline.

Maybe:

  • SEARCH: search object with some criteria
  • ORDERPATCH: order objects in the parent collection
  • MKCOL: create a new collection, does make sens only in few context

URL parsing

Each parts of the URL's path can be one the following:

  • if it starts with an uppercased letter, it is a property of the parent object (it converts to the regular camelCase property name)
  • if it is a 24 characters string of hexadecimal, it is a MongoID
  • if it contains only decimal, it is an offset (the index of the element into the collection)
  • if it is a string containing only character of the class [0-9a-z-], it is a SID
  • anything else is an error

SID (Slug ID)

This is a human-readable ID, both intended to make user-friendly and SEO-friendly URL. Also, a user's account identifier is a SID (rather than an email), this is consistent with Twitter @ syntaxe.

Requirement

  • a SID is a string, and should at least contains 3 characters, and at most 72 characters
  • allowed character are lowcase ascii alpha (a-z), digits (0-9) and hyphen (-)
  • if the string happens to be a valid MongoID hexadecimal representation or a valid decimal arbitrary number, then either an hyphen - is appended to transform it, or the SID creation is simply rejected

MongoID's client-side creation

The original MongoID are built this way:

Each MongoId is 12 bytes (making its string form 24 hexidecimal characters):
* 4 bytes for a timestamp
* 3 bytes are a hash of the client machine's hostname
* 2 bytes for the two least significant bytes of the process id running the script
* 3 bytes are an incrementing value

When creating a MongoID client-side, the 5 bytes shortAgentID is used as a replacement for the 2 middle part of the ID.

To sum up, the 12 bytes are built this way:

  • 4 bytes for a client-side timestamp
  • 5 bytes for the client's shortAgentID
  • 3 bytes are a client-side incrementing value

Across any REST query, ID are sent in hexadecimal-encoded string, being in the URI part or in the JSON body, or anything else.

MongoDB collections and documents requirement

Special collection: users

Collection's methods:

  • create (POST) : create a new user object, and return it

Object's data:

  • _id (userID) MongoID 12 bytes, generated by the auth server
  • SID SID here the SID is unique among all users
  • email Email a valid email where the user can be reached (unique or not?)
  • passwordHash String hash of the user password
  • clients Hashmap, each key is a clientID (MongoID), each value is a clientID object, where
    • isApiKey: false|string false if this is not an API key, if it is an API key this contains a string that describe the device and/or the app using it, no token is used and those clientID are rarely garbage collected
    • fingerPrint: string 10 hexadecimal chars representing 5 bytes used to create MongoId client-side
    • token: MongoID token with limited lifetime
    • lastUsed: Date last time the clientID/token was used

Object's methods:

  • auth (POST) : authenticate an user

Authentication

The access token the client receive and send is exchanged using cookie, it is produced by joining different parts:

accessToken: <userID>-<clientID>-<token>

It can be transfered using HTTP header, URL's query string or multipart/form-data as well. However, all operations that involve changing things (i.e. everything except GET) *MUST* provide this access token using anything except cookie, except if this accessToken is an API Key.

This is to prevent Cross-Site Request Forgery.

Special collection: auth

Object's data:

  • _id MongoID
  • collection String collection's name for this auth entry
  • userID MongoID the ID of the related user
  • objectID MongoID the ID of the object in the collection

Common properties of all application's collections

Object's data:

  • SID SID (optionnal) Slug ID, sometime unique, sometime only unique on the current path's directory
  • title String full featured title for this resource, most of time this property is used to create automatically a SID
  • parent Object, each key is the name of a collection, and each value is an ID of a parent object