There are several stages in the lifecycle of API development. You should always follow proper API design practices. Everyone says so. Perhaps 1% of those people actually do so. Looming deadlines, shortened dev cycles, and lack of appreciation for how intense the effort actually is often leave developers with insufficient time to allocate towards software design.

Realistically, creating a new API consists of alot of boilerplate activities. “Throw away” code is often written testing and development purposes, which ultimately winds up in the trash when you move to production. When code is treated as disposably as this, the end result never reflects the actual time commitment, which is a primary reason why people underestimate projects. I got tired of this nasty cycle, so I produced common-api to help. It’s an MIT-licensed Node module, so you’re free to use it in any project.

Ultimately, this project helped shift my attention/time from common API “development” infrastructure to purposeful design tasks (like writing logic that actually does something).

The following code block provides a small example of what’s possible.

Main Features

Request Middleware

• log
• logRequestHeaders
• litmusTest([message])
• validateJsonBody
• validNumericId
• validId
• validResult(res, callback)
• basicauth(user, password)
• bearer(token)
• applyCommonConfiguration(app, [autolog])
• applySimpleCORS(app, host='*')

Responses

• 200
• OK
• 201
• CREATED
• 401
• UNAUTHORIZED
• 404
• NOT_FOUND
• 501
• NOT_IMPLEMENTED
• reply(anything)
• replyWithError(res, [status, message]|error)
• replyWithMaskedError(res, [status, message]|error)

Utilities

• createUUID
• atob(value)
• applyBaseUrl (req, route = '/' [, forceTLS = false])
• applyRelativeUrl (req, route = '/' [, forceTLS = false])

Awesome. How do I use it?

This is an npm module, installed the same way any other module is installed. It is designed to work with Express.js.

npm init 
npm install express @ecor/common-api -S 

To get a very basic API running, use the following code:

const express = require('express') 
const API = require('@ecor/common-api') 
const app = express() 
 
API.applyCommonConfiguration(app) 
 
app.get('/hello', API.reply('Hello World.')) 
 
app.listen(8001) 

Then run node index.js. This will launch the API server on port 8001 (i.e. http://localhost:8001).

Testing It Out

I often use Postman to quickly/visually send HTTP test requests to API’s. The screenshot below shows the response you’ll get when you send a GET request.

Notice a few important things…

First, notice the runningSince attribute. The server automatically keeps track of when it was launched. This can be very helpful when you’re trying to remember “Did I refresh the server?” or asking “Am I seeing the latest changes?”

Second, it picks up on the version number identified in the package.json file. This can be really useful when you’re deploying to a QA server and wanting to know if you deployed the latest version.

Finally, see the routes attribute? All routes are identified, so you know all of the available endpoints. Three of them (ping, version, and info) are all generated by common-api’s applyCommonConfiguration method. Not too shabby, eh?

You can also see the /hello endpoint explicitly defined in the code.

The applyCommonConfiguration also invokes basic request logging automatically (by default). The two requests issued above generated the following output on my terminal:

Use It!

This little library has really helped save alot of time on proof of concept projects, new development, etc. If you use it, let me know. Star it on Github. Tweet it. If knowing about this would have been worth a coffee meeting to you, consider donating that coffee on Patreon :-)