Skip to content

Commit a8de410

Browse files
tjmehtatjmehta
committed
Merge pull request #449 from CodeNow/better-docs
Add docs for mapping between UI actions and API calls
2 parents afb9754 + 47e0b66 commit a8de410

3 files changed

Lines changed: 214 additions & 37 deletions

File tree

‎API.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
## Temporary API endpoints docs (initial coverage)
2+
3+
4+
### UI and API relationships
5+
============================
6+
7+
Description of what API calls are made when user performs UI actions.
8+
9+
10+
11+
#### New box (press "New box" button)
12+
13+
```
14+
POST /contexts
15+
request:
16+
name: uuid()
17+
owner:
18+
github: user_github_id
19+
response:
20+
new context object
21+
22+
POST /contexts/:new_context_id/versions
23+
request: empty
24+
response:
25+
new context version object
26+
27+
POST /builds
28+
request:
29+
contextVersions: [:new_context_version_id]
30+
owner:
31+
github: user_github_id
32+
response:
33+
new build object
34+
```
35+
36+
#### Add repo to the box (press "Add repository to the box" area)
37+
38+
```
39+
POST /contexts/:new_context_id/versions/:new_context_version_id/appCodeversions
40+
request:
41+
branch: branch name
42+
commit: commit
43+
repo: full repo name (owner/name)
44+
response:
45+
new app version code
46+
```
47+
48+
49+
### Select Docker template (click on template)
50+
51+
```
52+
PUT /contexts/:new_context_id/versions/:new_context_version_id/infraCodeVersion/actions/copy?sourceInfraCodeVersion=5452c94e72fd5a2400e72430
53+
GET /contexts/:new_context_id/versions/:new_context_version_id/files
54+
GET /contexts/:new_context_id/versions/:new_context_version_id/files/Dockerfile
55+
```
56+
57+
### Enter new Dockerfile content
58+
59+
```
60+
PATCH /contexts/:new_context_id/versions/:new_context_version_id/files/Dockerfile
61+
```
62+
63+
### Enter box name and press "Create box"
64+
65+
```
66+
POST /builds/:new_build_id/actions/build
67+
request:
68+
message: 'Initial Build'
69+
response:
70+
updated build object
71+
72+
POST /instances
73+
request:
74+
build: 'Initial Build'
75+
name: instance name
76+
owner:
77+
github: user_github_id
78+
response:
79+
new instance object
80+
```
81+
82+
83+
### Rename box
84+
85+
```
86+
PATCH /instances/:id
87+
request:
88+
name: new name
89+
response:
90+
update instance object
91+
```
92+
93+
94+
### Edit box
95+
96+
```
97+
POST /builds/:build_id/actions/copy?deep=true
98+
request: empty
99+
response:
100+
new build object
101+
102+
// change docker file
103+
PATCH /contexts/:context_id/versions/:context_version_id/files/Dockerfile
104+
request:
105+
body: docker file content
106+
response:
107+
file object
108+
// build a build
109+
POST /builds/:new_build_id/actions/build
110+
request:
111+
message: "Manual build"
112+
response:
113+
build object
114+
// poll container until found. Containers will always have one container!
115+
GET /instances/:instance_id/containers
116+
response: [new container object]
117+
// patch instance with a new build
118+
PATCH /instances/:instance_id/
119+
request:
120+
build: build_id
121+
response:
122+
instance object
123+
```
124+
125+
126+
### Stop box
127+
128+
```
129+
PUT /instances/:instance_id/actions/stop
130+
```
131+
132+
### Stop box
133+
134+
```
135+
PUT /instances/:instance_id/actions/stop
136+
```
137+
138+
### Fork box
139+
140+
```
141+
POST /instances/:instance_id/actions/copy
142+
request:
143+
name: forked box name
144+
response:
145+
instance object
146+
```
147+
148+
149+
### Update box to commit version
150+
151+
```
152+
// create new context verison
153+
POST /contexts/:context_id/versions
154+
request:
155+
infraCodeVersion: id of existing infracode version
156+
response:
157+
new contex version withou appCode
158+
// create new app code version
159+
POST /contexts/:context_id/versions/:created_context_version_id/appCodeVersions/
160+
request:
161+
branch:
162+
commit:
163+
repo:
164+
response:
165+
new app code version
166+
// create new build
167+
POST /builds
168+
request:
169+
owner: github owner data
170+
contextVersions: [context version id]
171+
response:
172+
new build object
173+
// build a build
174+
POST /builds/:new_build_id/actions/build
175+
request:
176+
message: "Update application code version(s)"
177+
response:
178+
build object
179+
// patch instance with a new build
180+
PATCH /instances/:instance_id/
181+
request:
182+
build: build_id
183+
response:
184+
instance object
185+
```

‎README.md‎

Lines changed: 26 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33
Application Components
44
==========
55
#### Express
6-
/lib/app.js
6+
/lib/express-app.js
77

88
#### Routes
9-
/lib/routes.js
9+
/lib/routes/**/*.js
1010

1111
#### Mongo
1212
Models - /lib/models/mongo/*.js
@@ -15,7 +15,7 @@ Schemas - /lib/models/mongo/schemas/*.js
1515
#### Tests
1616
Behavioral tests (BDD) - /test
1717
Unit Tests - /unit
18-
Lab - Testing Framework - [spumko/lab](https://github.com/spumko/lab)
18+
Lab - Testing Framework - [hapijs/lab](https://github.com/hapijs/lab)
1919

2020
Running Tests
2121
=============
@@ -27,47 +27,43 @@ npm test
2727

2828
Granular:
2929

30-
Lint: `npm run lint`
31-
All BDD: `npm run bdd`
32-
Pass additional arguments to BDD: `npm run bdd -- -d`
33-
BDD one file: `npm run bdd -- test/path/to/file.js`
34-
BDD Watch: `npm run bdd-watch`
35-
BDD Watch w/ one test file: `npm run bdd-watch -- test/path/to/file.js`
36-
All Unit: `npm run unit`
30+
Lint: `npm run lint`
31+
All BDD: `npm run bdd`
32+
Pass additional arguments to BDD: `npm run bdd -- -d`
33+
BDD one file: `npm run bdd -- test/path/to/file.js`
34+
BDD Watch: `npm run bdd-watch`
35+
BDD Watch w/ one test file: `npm run bdd-watch -- test/path/to/file.js`
36+
All Unit: `npm run unit`
3737

3838
Opinions
3939
========
4040
#### Restful resource urls
41-
Create - POST - /resources
42-
Read - GET - /resources/:id
43-
Update - PATCH - /resources/:id *PATCH is a partial update, PUT is a full resource update
44-
Delete - DELETE - /resources/:id
41+
Create - POST - /resources
42+
Read - GET - /resources/:id
43+
Update - PATCH - /resources/:id *PATCH is a partial update, PUT is a full resource update
44+
Delete - DELETE - /resources/:id
4545

4646
#### Middleware Patterns
47-
Request Data validation and Middleware Flow Control - [tjmehta/dat-middleware](https://github.com/tjmehta/dat-middleware)
48-
Middleware Flow Control - [tjmehta/middleware-flow](https://github.com/tjmehta/middleware-flow)
49-
Middlewares of models are autogenerated for you
50-
* Mongoose Models - /lib/middlewares/mongo/index.js - [tjmehta/mongooseware](https://github.com/tjmehta/mongooseware)
51-
* Class Models - /lib/middlewares/apis/index.js [tjmehta/middlewarize](https://github.com/tjmehta/middlewarize)
52-
Sharing the request object as a common context between middlewares allows us to make
53-
asyncronous code look syncronous and avoid "callback hell"
47+
48+
Request Data validation and Middleware Flow Control - [tjmehta/dat-middleware](https://github.com/tjmehta/dat-middleware)
49+
Middleware Flow Control - [tjmehta/middleware-flow](https://github.com/tjmehta/middleware-flow)
50+
Middlewares of models are autogenerated for you
51+
* Mongoose Models - /lib/middlewares/mongo/index.js - [tjmehta/mongooseware](https://github.com/tjmehta/mongooseware)
52+
* Class Models - /lib/middlewares/apis/index.js [tjmehta/middlewarize](https://github.com/tjmehta/middlewarize)
53+
Sharing the request object as a common context between middlewares allows us to make
54+
asynchronous code look synchronous and avoid "callback hell"
55+
5456

5557
#### Boom for Http Errors
56-
Nice Http Error library - [spumko/boom](https://github.com/spumko/boom)
58+
Nice Http Error library - [hapijs/boom](https://github.com/hapijs/boom)
5759

5860

5961

6062
Resource Overview
6163
=================
6264
Mongo Schemas - /lib/models/mongo/schemas/*.js
6365

64-
Configs - Are a way of forking Infrastructure Code of a Project's Components
65-
66-
Components - are application components. Ex: frontend-server, api-server, database
67-
* Infrastructure code - environment definition code
68-
* Application code - node.js code or etc. (github)
69-
70-
Component Versions - a snapshot of infrastructure code version and application code version
66+
Context Versions - a snapshot of infrastructure code version and application code version
7167
* Dockerfile v0.1.0 and api-server v0.1.0
7268
* Can be built on unbuilt
7369

@@ -107,11 +103,6 @@ npm run client-version # this will update the client's version to the latest in
107103
```
108104
Models:
109105
110-
projects (full blown project - that has multiple components)
111-
- environments (subdoc)
112-
- builds (collection)
113-
- versions (collection) [redis v0.7, api v0.8, mongo v2.7]
114-
115106
116107
A context represents a project context (like redis)
117108
A version is a version of a particular context (build files, github commitHash)
@@ -144,5 +135,4 @@ Instance Page - /project/anandkumar/filibuster/master/build/:id (just like our c
144135
- create an instance from a build (create containers for all build images (versions))
145136
```
146137

147-
![Magic](https://s3.amazonaws.com/uploads.hipchat.com/31372/651154/nARA3Q63eW1j5WV/2014-07-04-14-45-39%20%281%29.png)
148-
138+
![Magic](https://s3.amazonaws.com/uploads.hipchat.com/31372/651154/nARA3Q63eW1j5WV/2014-07-04-14-45-39%20%281%29.png)

‎lib/routes/builds.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ var findBuild = flow.series(
3737
me.isModerator));
3838

3939
/** Create a build
40+
* @param {Object} body.owner build owner
41+
* @param [String] body.contextVersions array with one context version id.
4042
* @returns [Build, ...]
4143
* @event POST /builds/
4244
* @memberof module:rest/builds */
@@ -175,7 +177,7 @@ app.post('/builds/:id/actions/copy',
175177
mw.res.json('build'));
176178

177179
/** Build a build
178-
* @param id buildId of the build to build (say that ten times fast)
180+
* @param id buildId of the build to build
179181
* @returns Build
180182
* @event GET /builds/
181183
* @memberof module:rest/builds */

0 commit comments

Comments
 (0)