Github user tae-jun commented on the issue:
@minahlee Oh, in that context, it makes sense. LGTM.
But, after looking all around Notebook REST API, it works well now but it doesn't seem RESTful. I summarized current list of REST API:
- `GET` /
- `POST` /
- `GET` /[noteId]
- `POST` /[noteId]
- `DELETE` /[noteId]
- `GET` /job/[noteId]
- `POST` /job/[noteId]
- `DELETE` /job/[noteId]
- `GET` /job/[noteId]/[paragraphId]
- `POST` /job/[noteId]/[paragraphId]
- `DELETE` /job/[noteId]/[paragraphId]
- `POST` /run/[noteId]/[paragraphId]
- `GET` /cron/[noteId]
- `POST` /cron/[noteId]
- `DELETE` /cron/[noteId]
- `GET` /search?q=[query]
- `POST` /[noteId]/paragraph
- `GET` /[noteId]/paragraph/[paragraphId]
- `DELETE` /[noteId]/paragraph/[paragraphId]
- `POST` /[noteId]/paragraph/[paragraphId]/move/[newIndex]
- `GET` /export/[noteId]
- `POST` /import
A good REST API is API that doesn't need a documentation, which means users can understands only with HTTP method and URL. So, it should be simple. However, I think some of current API may need to be changed.
REST API is UI for developers, so should be well designed. There are problems I can see now:
- Need to organize resources of Zeppelin: hierarchy of resources, and what they have; For example:
- Need hierarchical URL design: `notebook/:noteId/paragraphs/:paragraphId/
- Do jobs belong to notebook or paragraph?
- Use plural
- Use nouns as far as you can, no verbs. Make use of HTTP methods. URL should point resources.
- For in the case of a request that doesn't fit CRUD(Create(POST), Read(GET), Update(PUT|PATCH), Detele(DELETE)), we need a rule for this. Heroku deals with this by placing actions for the resource under `/actions`. For example, in our case, run all paragraphs can be represented as `POST notebook/:noteId/actions/run`
- Need API versioning
Zeppelin needs more REST API, so eventually, it will be getting bigger. I think it's time to organize REST APIs. After all of this, the REST API documentation should also be updated. Not by listing actions what you can, just by listing APIs. This is easier to read since users can know what they can do with resources.
Would you mind if I open an issue for this?