Code generated for both client- and server-side. Note: The project is still in early stages.
npm install -g cgapis
cgapis --spec api.json
└───generated ├───client └───server └───api
REST over HTTP doesn't gaurantee API synchronization between the server and the clients. Changes made to the API on the server have to be reflected at each client. This is done manually, which wastes time, and is boring. We can automate that. Also, the API has to be clearly defined and agreed upon by both client-side and server-side developers. This eliminates any conflicts that would otherwise arise later on.
RESTful isn't an agreed upon standard. Everybody has his own "standard", opinions, and "best practices". HTTP verbs aren't enough to express all functionalities of the web service, if your logic isn't just about GET, POST, PUT, PATCH, DELETE. For example, let's say I have a
Course Collection/Table, which contains a curriculum, which is an array of
Sections and within each section is an array of
Nodes which contain the content of the course, i.e., the learning material.
Now, how would you map the following to HTTP verbs?:
Developers views on this would vary, simply because there are many ways to do this. My point is, don't bother. Besides, wouldn't it be more practical to deal with methods on objects directly?.
HTTP status codes are predefined generic messages. Trying to communicate through status codes is a futile endavor. Instead, we can define application specific status codes (error codes, specifically) that make sense to the client, and are discoverable through auto-completion. Afterall, robust systems are designed to handle errors well. That means clients know what errors servers might return, and handle each error accordingly, leaving no errors unhandled!.
Alot of code on the client side to make requests to specific URLs are just repetetive and prone to error, because there is no automatic checker that tells us whether we made a mistake in the URL, or how the parameter names are not right, or any other detials. We can solve this problem. And we can let the computer write this low-level code for you.
Besides, I want to roll out my own generator, because I want to explore something new.
Abstract the low-level code, and write the required boilerplate code. Let the user deal with the API directly, calling methods, and getting return values, as if doing RPC. Just write
api.json, a declaration of the API in terms of services and data, much like methods and parameters. Abstracting away the low-level primitives such as URL endpoints, HTTP methods, request headers and body, query strings, ...etc.
Currently, the JSON file is formatted like so:
services: like namespaces. For organizing operations together
ops: methods/functions in a service
req: describes function parameters. (
reqis short for request)
res: describes function return values. (
resis short for response)
refs: defines user-defined data types (yet to be implemented)
Note: because this is under development, many things, including the format of the JSON file, are subject to change.
It is redundant to do validation both client- and servers-side. We can solve this problem by defining our data types once, and have the program generate all the runtime validation code required. The
ajv (Another JSON Schema Validator) library would be used for validating schemas. The library implements the JSON-Schema standard, which makes it interoperable with other libraries as well. Custom validation code is a concern that we'll try to address as well.