Github user tae-jun commented on the issue:
https://github.com/apache/zeppelin/pull/1565
@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/{title|text|result|job}`
- 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?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
