Generates client-side & server-side code from API specification files
MIT License
cgapis
generates client-side SDKs and server-side APIs from specification files.
npm install -g cgapis # install globally to use from any directory
Start by copying the two directories /api-schemas
and /api-services
, then run:
cgapis
This will generate two output directories /generated-server
and /generated-client
.
Note: configuration files and CLI arguments are not yet implemented.
Unlike GraphQL and JSON-RPC, cgapis is cacheable by default.
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:
I would like to just call SDK.Course.dislike(courseID, userID)
, or SDK.Node.addComment(nodeID, comment)
. What do you think?
Low-level primitives such as URL endpoints, HTTP methods, request body, query strings, URL encoding, content-type, ...etc are inferred by our smarter generators and abstracted away from the user (still available if needed).
Developers agree to define:
/api-services
a namespace for operations/api-schemas
defined using JSON Schema draft-07
req
) and response (res
)Then, you cd
into the directory where /api-services
and /api-schemas
exist, and run the command cgapis
. You'll see the output as two directories: /generated-client
and /generated-server
.
We would like to provide a way to detect changes in specification changes. (not implemented yet)
We're using RPC over HTTP: basically, a remote procedure URL is as follows: http://<hostname>/api/<service>/<method>
. Using only two HTTP methods to do CRUD: GET
for "Read" operations and POST
for "Create", "Update", "Delete" operations. The generated code uses whatever network library there is to pass/recieve requests/responses between the client and the server, exposing a unified interface to application code both on the server (named: API) and the client (named: SDK). The interface contains methods on services and data types.
Language/Frameworks | |
---|---|
Client SDKs | Browser (Axios) |
Server APIs | Node (Express.js) |
Generators for each language is at /generators/<lang>/[client|server]/<framework>.js
.
File / Directory | Description |
---|---|
index.js |
Main entry |
config.js |
Configuration |
cmd.js |
Command-Line Interface (overwrites config) |
spec.js |
Exports {schemas, services} after reading, parsing, and normalizing /api-schemas and /api-services
|
/generators/semantics.js |
Helper functions for all languages |
/generators/<lang>/common/ |
Help functions for <lang> shared across frameworks |