[PR] Reorganizing and enhancing document #47
Conversation
…ols. #46 The guide of design and tips for structuring an API correctly will be made on a second parter.
Only missing the documentation and performance testing sections.
LuchoTurtle
added
enhancement
LuchoTurtle
changed the title
|
Took a little longer to delve deeper into versioning and adding best API practices/standardization. I'm close to finishing this and will be done by Monday for sure. I want to give a comprehensive guide to documenting and doing stress/performance tests on APIs (still need to do more research for the best options). Pruned links, added new ones and deleted resources that were outdated or outright 404'd. |
LuchoTurtle
added
awaiting-review
|
The refactoring of the whole document should now be complete. I tried to maintain the pre-existing content (it was impossible sometimes, a few links were 404) and added new content according to #46 . I initially intended to add more but I think having sections concise is a much easier read. Let me know if there is something missing/ if I should elaborate more in any topic. |
|
Thanks @LuchoTurtle will go through this PR next. 👍 |
| @@ -1231,6 +1231,11 @@ Besides managing different collaboratively APIs, | |||
| creating Open API specifications, | |||
| documentation | |||
| and monitoring. | |||
| - [**Insomnia**](https://insomnia.rest/): | |||
| similar to Postman, it's a API platform | |||
There was a problem hiding this comment.
| similar to Postman, it's a API platform | |
| similar to Postman, but ***`Open Source`***, is an `App` |
nelsonic
added
in-review
|
Picking up the review on this now as I've seen a couple of links to this in https://github.com/dwyl/mvp/pull/263/files#r1070223004 and rather than having to update the link: Would be better if it linked directly to the So this is my side quest for the next hour. 🧑💻 👀 ⏳ |
README.md
Outdated
| or Twitch's [`Twirp`](https://blog.twitch.tv/en/2018/01/16/twirp-a-sweet-new-rpc-framework-for-go-5f2febbf35f/) | ||
| use `gRPC` for internal communication between microservices. | ||
|
|
||
| In these services, as *millions* of calls are made per-day, |
There was a problem hiding this comment.
This is a very long sentence.
Please avoid writing sentences with more than 25 words as it dramatically lowers readability.
The average person would totally lose track of what they are reading half way into reading this.
Not saying that the people reading this doc are "stupid", they obvs aren't!
It's a highly technical doc aimed at an educated audience.
But just so you get into the habit of improving the readability of your writing for all areas of your communication. Write shorter sentences. Thank me later. 👌
There was a problem hiding this comment.
@LuchoTurtle thank you very much for taking the time to do this 2023 refresh/update! 🎉
Lots of great new info and good to get it re-read by someone with fresh eyes and enhanced! 🚀
Still a few things we can add - will open a new issue - but this is an excellent update. Thanks again! 🙏
closes #46
This PR will effectively reorganize the document, make it more structure and add sections that delve into more detail according to API design and best practices.