https://github.com/mooreniemi/choclety
a hypermedia api spec grapher
https://github.com/mooreniemi/choclety
cytoscape graph hypermedia web
Last synced: 8 months ago
JSON representation
a hypermedia api spec grapher
- Host: GitHub
- URL: https://github.com/mooreniemi/choclety
- Owner: mooreniemi
- License: mit
- Created: 2017-01-30T19:44:28.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2017-02-11T20:34:36.000Z (over 8 years ago)
- Last Synced: 2025-01-23T00:27:57.158Z (9 months ago)
- Topics: cytoscape, graph, hypermedia, web
- Language: Ruby
- Size: 566 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# choclety
a hypermedia api-spec grapher, based on [this blog post](http://mooreniemi.github.io/apis/web/rest/2017/01/04/when-is-an-api-better-or-worse.html)
## purpose
Input: an api spec file.
Output: a useful graph of your api, and maybe your api itself.
Here's a screenshot of the example output, with shortest path to your revenue generating node highlighted:
And [here's a hosted version](https://mooreniemi.github.io/choclety/) you can click around on.
## usage
### graph output
To generate a [cytoscape graph](http://js.cytoscape.org/), run `./choc g .json`, ie.:
```
./choc g ApiSpecs/api-spec.json
./choc g ApiSpecs/api-spec-2.json
./choc g ApiSpecs/api-spec-3.json
```
Then run a server in the root directory to view, ie.:
```
python -m SimpleHTTPServer 8000
```
### api output
To generate an api, run `./choc a .json`, ie.:
```
./choc a ApiSpecs/api-spec.json
```
Currently we're just generating a [single file Sinatra app](http://www.sinatrarb.com/contrib/json.html), so you can run it using `ruby YourAppName.rb`.
## the spec format
Is not formalized. But essentially forces you to write your API spec as a graph in the form of an edge list and a node list. `choc` is building adjency lists for you automatically. Technically we could get everything we need from edges, but then they start to get a ton of properties.
The spec format at the top level requires:
```json
{
"state_transitions": [],
"state_representations": []
}
```
For generating a graph, `StateTransition`s require:
```json
{
"source": "from node",
"target": "to node",
"link_relation": "edge label",
"verb": "protocol specific modifier for your remote call, ie. POST in http"
}
```
For generating an api, `StateTransition`s require one of the 3 or they will have urls generated by convention:
```json
{
"url_template": "function signature of your remote call",
"url_template_type": "named templates, ie. collection_item",
"url": "static direct url"
}
```
For generating a graph or api, `StateRepresentation`s require:
```json
{
"name": "name of representation, must be unique. namespace with . if necessary, ie. namespace.name",
"noun": "special values for our graph describing their representation type, understood values: generated_revenue|error|null"
}
```