Declarative REST API

16 June 2018

library node async objects

We all are used to MVC for building REST applications. In this article, I'll show how you can build REST API using declarative approach. It'll be demonstrated on my library cutie-rest which was released recently.

Let's start with interface Endpoint and some default built-in implementations of this interface that this library provides.

`Endpoint(regexpUrl, method(string)[, ...args])`

This interface declares an endpoint (in api) with url that matches regexpUrl and specified method ('GET', 'POST', etc.) in arguments of constructor. Also it's possible to pass some custom arguments via ...args. This class has a method body(request, response[, ...args]) that needs to be overridden and must return async object.

It's important to mention that Endpoint is not an AsyncObject. And that's how you can implement it:

const { Endpoint } = require('@cuties/rest')
const {
  ResponseWithHeader,
  ResponseWithStatusCode,
  ResponseWithStatusMessage,
  WrittenResponse,
  EndedResponse
} = require('@cuties/http')

class CustomEndpoint extends Endpoint {
  constructor (regexpUrl, type) {
    super(regexpUrl, type)
  }

  body (request, response) {
    return new EndedResponse(
      new WrittenResponse(
        new ResponseWithHeader(
          new ResponseWithStatusMessage(
            new ResponseWithStatusCode(response, 200), 'Ok'
          ),
          'Content-Type', 'text/plain'
        ),
        'Index.'
      )
    )
  }
}

To handle request and response in the method body you can use cutie-http.

`NotFoundEndpoint(regexpUrl)`

This interface (or abstract class) extends Endpoint, and it declares endpoint on 404(NOT_FOUND) status.

And that's how it's implemented:

const { Endpoint } = require('@cuties/rest')
const {
  ResponseWithHeader,
  ResponseWithStatusCode,
  ResponseWithStatusMessage,
  WrittenResponse,
  EndedResponse
} = require('@cuties/http')

class NotFoundEndpoint extends Endpoint {
  constructor (regexpUrl) {
    super(regexpUrl, 'GET')
  }

  body (request, response) {
    return new EndedResponse(
      new WrittenResponse(
        new ResponseWithHeader(
          new ResponseWithStatusMessage(
            new ResponseWithStatusCode(response, 404), 'Not found'
          ),
          'Content-Type', 'text/plain'
        ),
        '404: Not found'
      )
    )
  }
}

You can create your custom variation of Endpoint. Just extends this default class with redefined method body.

`IndexEndpoint()`

It's an Endpoint that is used for representing index page.

const { Endpoint } = require('@cuties/rest')
const {
  ResponseWithHeader,
  ResponseWithStatusCode,
  ResponseWithStatusMessage,
  WrittenResponse,
  EndedResponse
} = require('@cuties/http')

class IndexEndpoint extends Endpoint {
  constructor () {
    super(new RegExp(/^(\/|)$/), 'GET')
  }

  body (request, response) {
    return new EndedResponse(
      new WrittenResponse(
        new ResponseWithHeader(
          new ResponseWithStatusMessage(
            new ResponseWithStatusCode(response, 200), 'Ok'
          ),
          'Content-Type', 'text/plain'
        ),
        'Index.'
      )
    )
  }
}

`InternalServerErrorEndpoint(regexpUrl)`

It's an Endpoint that is used for handling underlying internal failure(not for user error) with status code 500.

const { Endpoint } = require('@cuties/rest')
const {
  ResponseWithHeader,
  ResponseWithStatusCode,
  ResponseWithStatusMessage,
  WrittenResponse,
  EndedResponse
} = require('@cuties/http')

class InternalServerErrorEndpoint extends Endpoint {
  constructor (regexpUrl) {
    super(regexpUrl || new RegExp(/^\/internal-server-error/))
  }

  body (request, response, error) {
    return new EndedResponse(
      new WrittenResponse(
        new ResponseWithHeader(
          new ResponseWithStatusMessage(
            new ResponseWithStatusCode(response, 500), 'Internal Server Error'
          ),
          'Content-Type', 'text/plain'
        ),
        `500: Internal Server Error, \n${error}`
      )
    )
  }
}

Here method body also handles an error.

Now let's talk about other objects that REST API declaration consists of: Backend, RestApi, RequestBody, CreatedServingFilesEndpoint, CreatedCachedServingFilesEndpoint, ServingFiles, and CachedServingFiles.

Let's take a look on a simple declaration of REST API.

const {
  Backend,
  RestApi,
  CreatedServingFilesEndpoint,
  CreatedCachedServingFilesEndpoint
} = require('@cuties/rest');
const path = require('path')
const SimpleResponseOnGETRequest = require('./SimpleResponseOnGETRequest')
const SimpleResponseOnPOSTRequest = require('./SimpleResponseOnPOSTRequest')
const CustomNotFoundEndpoint = require('./CustomNotFoundEndpoint')
const CustomInternalServerErrorEndpoint = require('./CustomInternalServerErrorEndpoint')
const CustomIndexEndpoint = require('./example/CustomIndexEndpoint')
const notFoundEndpoint = new CustomNotFoundEndpoint(new RegExp(/\/not-found/))
const internalServerErrorEndpoint = new CustomInternalServerErrorEndpoint(new RegExp(/^\/internal-server-error/))

const mapper = (url) => {
  let parts = url.split('/').filter(part => part !== '')
  return path.join(...parts)
}

const cacheMapper = (url) => {
  let parts = url.split('/').filter(part => part !== '').slice(1)
  parts.unshift('files')
  return path.join(...parts)
}

new Backend(
  'http', 
  8000, 
  '127.0.0.1',
  new RestApi(
    new CustomIndexEndpoint(),
    new SimpleResponseOnGETRequest(new RegExp(/^\/get/), 'GET'),
    new SimpleResponseOnPOSTRequest(new RegExp(/^\/post/), 'POST'),
    new CreatedServingFilesEndpoint(new RegExp(/^\/files/), mapper, {}, notFoundEndpoint),
    new CreatedCachedServingFilesEndpoint(new RegExp(/^\/cached/), cacheMapper, {}, notFoundEndpoint),
    notFoundEndpoint,
    internalServerErrorEndpoint
  )
).call()

`Backend(protocol, port, host, api[, options])`

It's an AsyncObject. It declares a backend server with protocol (http or https) on specified port and host, also it provides declared api, options of the http/https server (it's optional).

`RestApi(...endpoints)`

Represents request-response listener. Declares endpoints of api.

`RequestBody(request)`

Reads body of request in body(request, response) method of Endpoint implementation.

`ServingFilesEndpoint(regexpUrl, mapper, headers, notFoundEndpoint)`

Extends Endpoint and serves files on url that mathes regexpUrl with mapper function that gets location of a file on a disk by the url of incoming request. Also it's required to declare notFoundEndpoint that handles the cases when a file is not found. You also can specify headers in response(no need to specify the 'Content-Type', library makes it for you).

`CachedServingFilesEndpoint(regexpUrl, mapper, headers, notFoundEndpoint)`

Does the same that ServingFilesEndpoint does and caches files for increasing speed of serving them.

`CreatedServingFilesEndpoint(regexpUrl, mapper, headers, notFoundEndpoint)`

It's an AsyncObject that represents ServingFilesEndpoint. So, you can use its arguments as async objects.

`CreatedServingFilesEndpoint(regexpUrl, mapper, headers, notFoundEndpoint)`

It's an AsyncObject that represents CachedServingFilesEndpoint. So, you can use its arguments as async objects.

Let's see now how CustomIndexEndpoint, CustomNotFoundEndpoint, SimpleResponseOnGETRequest, SimpleResponseOnPOSTRequest and CustomInternalServerErrorEndpoint are implemented.

class CustomIndexEndpoint extends IndexEndpoint {
  constructor () {
    super()
  }

  body (request, response) {
    return super.body(request, response)
  }
}

class CustomNotFoundEndpoint extends NotFoundEndpoint {
  constructor (regexpUrl) {
    super(regexpUrl)
  }

  body (request, response) {
    return super.body(request, response)
  }
}

class SimpleResponseOnGETRequest extends Endpoint {
  constructor (regexpUrl, type) {
    super(regexpUrl, type)
  }

  body (request, response) {
    return new EndedResponse(
      new WrittenResponse(
        new ResponseWithWrittenHead(
          response, 200, 'ok', {
            'Content-Type': 'text/plain'
          }
        ), 'content'
      ), ' is delivered'
    )
  }
}

class SimpleResponseOnPOSTRequest extends Endpoint {
  constructor (regexpUrl, type) {
    super(regexpUrl, type)
  }

  body (request, response) {
    // request also contains body(as buffer), use RequestBody object for that
    return new EndedResponse(
      new WrittenResponse(
        new ResponseWithWrittenHead(
          response, 200, 'ok', {
            'Content-Type': 'text/plain'
          }
        ), new RequestBody(request)
      ), ' is delivered'
    )
  }
}

class CustomInternalServerErrorEndpoint extends InternalServerErrorEndpoint {
  constructor (regexpUrl) {
    super(regexpUrl)
  }

  body (request, response, error) {
    return super.body(request, response, error)
  }
}

So, here is some examples of requests:

curl http://127.0.0.1:8000/
# Index.

curl http://127.0.0.1:8000/get
# content is delivered

curl -X POST  http://127.0.0.1:8000/post -d "content"
# content is delivered

curl http://127.0.0.1:8000/bad-url
# 404: Not found

References

cutie-rest on GitHub