cgapis generates code client-side and server-side from API specification files.
npm install -g cgapis # install globally to use from any directory
Start by copying the two directories
/api-services, then run:
Usage: cgapis [options] [command] Generates client-side & server-side code from API specification files Options: -V, --version output the version number -p, --schemas-dir <path> Directory of API Schemas -P, --services-dir <path> Directory of API Services -a, --api-version <version> API Version -S, --server-dir <path> Directory for the generated server-side code -C, --client-dir <path> Directory for the generated client-side code -c, --client-lang <lang-framework> client language and framework -s, --server-lang <lang-framework> server language and framework -h, --help output usage information
Developers agree to define:
/api-servicesa namespace for operations
/api-schemasdefined using JSON Schema draft-07
req) and response (
cd into the directory where
api-schemas exist, and run the command
cgapis. You'll see the output as two directories:
If you make changes to services or schemas and want to add those changes, then, you'll have to use the
diff subcommand, which doesn't work right now.
diff should take two versions of services and/or two versions of schemas and outputs the difference: i.e., additions and deletions.
Only Client and Server contain your code
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 would vary, simply because there are many ways to do it. Wouldn't it be more practical to just call
Course.dislike(courseID, userID), or
Node.addComment(nodeID, comment), and have the IDE help?
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 all errors, and to handle them 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 is 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. We can generate this low-level code, so that you can focus on actual application logic.
Start by copying a file from
/generator/server and change the code inside the
generate() function. The following is a table showing what each file/directory is for:
|File / Directory||Description|
||Command-Line Interface (overwrites config)|
||Implementation of client generators. Must export the method generate|
||Implementation of server generators. Must export the method generate|
||Helper functions used across all types of generators (not specific to any language)|
||Used by files in
||Used by files in