Document API & architecture #143
Conversation
|
Hey @Tweekism! I wrote the full-fledged API documentation in Additionally, I made a reasonably ugly draft for the documentation of the architecture of Vivify in Thank you!! When this is done I would ask you @tuurep to do the final review :) |
|
Ah, one more thing: This is for the state after #117 is merged |
|
Cool, lemme have a look. |
|
The API stuff looks really good! I think that is a big help to anyone wanting to use the API. There is a couple things I could point at if you like, I'll do that as a review thing, but you could publish it as is honestly. I'll start working on the architecture one as soon as I can. I'll go through it slowly and make sure I understand it as I add to it. |
|
|
||
| ## Path encoding | ||
|
|
||
| Vivify's endpoints are often accessed with the pattern `/<endpoint>/<path>` |
There was a problem hiding this comment.
Would it be fair to say they are always accessed with that pattern? I would consider just dropping the word often.
There was a problem hiding this comment.
We do have GET /health and DELETE /viewer at the root of the endpoints with no paths.
We could instead say something like
Current wording
Vivify's endpoints are often accessed with the pattern
/<endpoint>/<path>where path is a percent-encoded path in the file system.Suggestion
When accessing an endpoint corresponding to a path in the file system, use
/<endpoint>/<path>where<path>is percent-encoded.
Is that better? ^^
docs/architecture.md
Outdated
There was a problem hiding this comment.
Since this is a rough draft, probably makes more sense if I edit it offline using my local text editor and this awesome markdown viewer I found called Vivify 🤣
There was a problem hiding this comment.
Yes, sounds good! That's the idea that you write the whole thing haha, the stuff I wrote into the document is only for you, not for main :D
There was a problem hiding this comment.
Rgr. Do you plan to merge api.md and leave architecture.md out? I've already pulled it down so I can keep working on it.
There was a problem hiding this comment.
Ah, I don't mind. I was thinking to leave this PR laying around until you are done with the architecture document, I don't think we are in a big rush here. Or what do you think?
There was a problem hiding this comment.
Fine by me, I am... thinking about putting in a job app this week, and then its my weekend for kid wrangling duties, so I might not get to it soon is all.
Close #119