Documentation of API

[knutole]

Need to write a full documentation of all API endpoints.

See #253 for how this fits in with testing and refactors, which should be done together.

Documentation needed:

All routes.js must be documented like this.

• [x] Projects
  • [x] create
  • [x] delete
  • [x] update
  • [x] invite (etc)
• [x] Users
  • [x] update
  • [x] create
  • [x] delete
  • [x] add to contact list
  • [x] get store
  • [x] etc.
• [x] etc etc (see routes.js and add more to this list)

  Requirements

• [x] all documentation must be written in-line in the routes.js file itself like this
• [x] all endpoints must have:

/**
    * @api {post} /api/project/create Create a project
    * @apiName create
    * @apiGroup Project
    * @apiUse token
    * @apiParam {String} name Name of project
    *
    * @apiSuccess {JSON} Project JSON object of the newly created project
    * @apiSuccessExample {json} Success-Response:
    *     {
    *       "project": "project-o121l2m-12d12dlk-addasml",
    *       "deleted": true
    *     }
    */

• @api - POST or GET, endpoint, description
• @apiName - simple name
• @apiGroup - Category that shows up in left pane in docs
• @apiUse - use a predefined set of params. see here for example of token. This will include whatever is under the predefined set.
• @apiParam - type, name, description
• @apiSuccess - type, name, description of success response
• @apiSuccessExample - type, JSON object (or whatever response looks like)
• @apiError - name, description of possible errors

  Create docs

• create documentation with npm run-script apidocs (remember to run npm things from inside the container (eg. docker exec -it dev3systemapiccom_wu_1 bash then npm run-script apidocs)
• see docs in /public/docs/api/ or https://dev3.systemapic.com/docs/api/

---

References

• apiDocs: http://apidocjs.com/index.html

[knutole]

@IgorZiegler There is also lots of API documentation to do. I've started with some of the routes, would be great if you could continue. This goes closely hand-in-hand with testing, so it's good to get into both at the same time perhaps. See above, everything should be explained there.

do npm run-script apidocs to create docs, and see them at https://dev3.systemapic.com/docs/api/

[strk]

+1 this is very important

[knutole]

@IgorZiegler Can you please go over the API documentation?

• [ ] make sure all documentation is up to date in routes.js
• [ ] check routes on /docs/api/ that everything works
• [ ] create a list of missing api documentation (separate issue)
• [ ] create a list of api routes that do not have tests (separate issue)
• [ ] ...and create missing api docs and route tests (ie. the issues above)

Want to close this asap.

[IgorZiegler]

@knutole I begin to check all docs. you can see progress in the table below I am going to do more checks tomorrow

API v2

Current API DOCS

wu request	method	endpoint	api doc	api doc worked	test
PORTAL
Get portal	GET	/v2/portal	exist	yes	no
Get status	GET	/v2/status	exist	yes	yes
DATA
Create file	POST	v2/data/create	Added	yes	added
Share dataset	POST	/v2/data/share	exist	yes	yes
Delete dataset	POST	/v2/data/delete	exist	yes	yes
Update data	POST	/v2/data/update	Added	yes	yes
Get layers @ data	POST	/v2/data/layers	exist	Doesn't know how we can check it	yes
Download data	POST	/v2/data/download	added	yes	no
PROJECTS
Create project	POST	/v2/projects/create	exist	yes	yes
Update project	POST	/v2/projects/update	exist	yes	yes
Delete project	POST	/v2/projects/delete	exist	yes	yes
Add data to project	POST	/v2/projects/data	exist	yes	yes
Get public project	GET	/v2/projects/public	exist	yes	yes
Get private project	GET	/v2/projects/private	exist	yes	yes
Set project access	POST	/v2/projects/access	Added	yes	yes
Get project layers	POST	/v2/projects/layers	exist	yes	yes
USERS
Get session	GET	/v2/users/session	exist	yes	yes
Get token from password	GET	/v2/users/token	exist	yes	yes
Create user	POST	/v2/users/create	exist	yes	yes
Update user	POST	/v2/users/update	exist	yes	yes
Check if email unique	POST	/v2/users/email/unique	exist	yes	yes
Check if username unique	POST	/v2/users/username/unique	exist	yes	yes
Get invite link	GET	/v2/users/invite/link	exist	yes	yes
Invite user to project	POST	/v2/users/invite/project	exist	Doesn't know how we can check it	yes
Invite user	POST	/v2/users/invite	exist	Doesn't know how we can check it	yes
Reset password	POST	/v2/users/password/reset	exist	yes	yes
Request contact	POST	/v2/users/contacts/request	exist	yes	yes
Refresh token	POST	/v2/users/token/refresh	exist	yes	yes
Check token	POST	/v2/users/token/check	updated	yes	yes
Check token	GET	/v2/users/token/check	updated	yes	yes
LAYERS
Delete layer	POST	/v2/layers/delete	exist	yes	yes
Update layer	POST	/v2/layers/update	exist	yes	yes
Set CartoCSS	POST	/v2/layers/carto	added	yes	no
Get CartoCSS	GET	/v2/layers/carto	added	yes	no
Download layer	POST	/v2/layers/download	added	yes	no
Create layer	POST	/v2/layers/create	exist	yes	yes
Create default layer	POST	/v2/layers/create/default	added	yes	no
Reload meta	POST	/v2/layers/meta	added	yes	yes
Convert styleJSON to CartoCSS	POST	/v2/layers/carto/json	exist	Doesn't know how we can check it	yes
LEGENDS
Create legends	POST	/v2/legends/create	added	yes	need to add
HASHES
Create hash	POST	/v2/hashes/set	exist	Doesn't know how we can check it	yes
Get hash	GET	/v2/hashes/get	exist	yes	yes
LOG/ANALYTICS
Set analytics	POST	/v2/log	not clear
Get analytics	GET	/v2/log	outdated
Log error	POST	/v2/log/error	updated	worked, but very strange endpoint	no