Hi!
Recently I had an idea how to improve the development experience when creating NodeJS servers (in particular, with express). But first I would like to explain some problems I see with barebones express apps:
1) lack of API documentation. You need to learn/integrate Swagger or API Blueprint to get proper API docs
2) lack of automatic input/output validation. With JavaScript, it's a bit hard to control if everything is properly typed. You need to write validation yourself or employ some validator libs or JSON schema validators.
3) low discoverability. No easy way to generate client code with types and validation.
What I thought would be cool is to have a standard format to define all aspects of a server with HTTP API. This format should be simple and not entirely new. So I thought that JSX is excellent for this. With JSX a typical server looks like this:
<Service
id="hello-world-service"
port={3000}
version="0.1.0"
contact="orkon"
tags={['node', 'service']}
endpoint="http://dev.server.at.home"
>
<Middleware use={require('./middleware/logger')} />
<Group name="Hello" description="All routes related to saying Hello">
<Route
description={'Generates a message in the format "Hello :who!"'}
path="/hello/:who"
method="get"
handler={require('./handlers/getHello')}>
<Request>
<PathParameter name="who" type="string" />
</Request>
<Response schema={require('./schemas/getHello.res.json')} />
</Route>
</Group>
</Service>
const server = getExpressServer(compile(__dirname + '/definition.jsx'));
server.listen(3000, () => {
console.log('server started');
});
The cool things I see about it:
- easy to read (especially if you are familiar with JSX/React)
- easier to compose different APIs
- connects implementation with documentation
- allows generating input/output validators thanks to JSON Schema
- allows generating proper API docs
- allows discovering how to invoke the service
- hides the underlying framework (it can be express, koa, etc.)
- behind the JSX it is just plain JS classes/objects, so the use of JSX is optional
Project URL: https://github.com/OrKoN/api-express
Do you think it's a good idea?
Top comments (3)
Almost. Don't forget you can actually code in JS with it, and pass functions. It's not static XML, it just smells like it. ;P
Doing something like React Router can actually work:
If you are referring vast amounts of xml for mapping servlets in the web.xml, that became mostly obsolete when Java EE 6 was released, which was more than eight years ago. Most configuration in Java EE projects nowadays is done by annotations. In that regard the nest.js framework, which makes use of the ES7 decorators (which look nearly like Java annotations, except that the parentheses are never optional, resembles Java EE much more closely than this proposal.
Do you have some examples to show similarity? Isn't JavaScript like... Java? ;-)