Enhance: Update + Section on Perf Testing

[nelsonic]

@LuchoTurtle please read through this learning doc and comprehensively update it. 🙏
My understanding is that you have limited experience with public APIs. 💭
Please list the APIs you have used in a comment before you start work on this. 📝
Our objective is to capture as much knowledge as we can so that we can build the best possible API for our
SaaS Product so we need to do first-principals research/analysis of the best existing examples we can learn from. 👌

Todo:

• Read the README.md with a beginner's mind i.e. as if you were new to all this. 👀

• Go through all the links in the README.md and determine their relevance. 🔗

  • If any links are no longer relevant, please drop a comment in this thread and remove the link. ✂️

• Find links to the best Public REST + Realtime APIs. Some Googling/Research required. 🔍

  • Show example request/responses where applicable. 🧑‍💻

• Add new section on performance and reliability testing for APIs.
  e.g: imagine we are building an API for our SaaS Product and want to run a series of performance tests each time a commit is made and pushed on a PR. i.e. on GitHub Actions. What is required for that?

  • Second, how do we monitor the "health" of an API so we know immediately when it has degraded performance?

This is at least a day worth of reading, research and write-up. ⏳
We need to make this investment up-front so that we can make the best possible API we can. 🙏

[LuchoTurtle]

The only public APIs that I've worked with were related to Microsoft's Graph for logging in users inside Azure tenants, and Google Cloud Console's for some personal projects, etc...

I'll take a look at this once learn-payment-processing is complete.

[nelsonic]

Cool. So you're not a complete n00b (didn't think you were)
MSFT & GOOG APIs are decent but both of those don't have the best docs/examples.
The best I've found was Twilio or Stripe which you are exploring now as part of /dwyl/learn-payment-processing ...
but there must be better examples and we need to uncover them. 🙏

Note: we will be using both of these APIs in due course so good to read through them.
This will be a good exercise for you to do some research & analysis. 👌

A good place to crowd-source "Good API Design" is HackerNews, e.g:
https://hn.algolia.com/?dateRange=all&page=0&prefix=true&query=api%20design&sort=byPopularity&type=story
Top link is: https://news.ycombinator.com/item?id=13706618
which discusses: https://cloud.google.com/apis/design
This might be a good guide. 💭

[LuchoTurtle]

I'm still in the process of writing this but I'm restructuring the document, as I felt it lacked some organization and structure.
I want to have a whole "part" dedicated to proper API implementation practice, so I'm splitting the document effectively in two.

I've deleted/updated and added a few links. I'm going to specify which links were deleted and the reason why:

• Google Developers Intro to REST: https://www.youtube.com/watch?v=YCcAE2SCQ6k

Deleted because it was redundant with another link pertaining to an Intro on RESTful APIs.

• Apigee Youtube channel for API management, design pattern and summit talks: https://www.youtube.com/user/apigee

Deprecated and moved to another channel -> https://www.youtube.com/channel/UCJS9pqu9BzkAMNTmzNMNhvg

• REST Wikipedia: http://en.wikipedia.org/wiki/REST

Was already linked prior.

• Basic Q&A for REST: http://katgleason.tumblr.com/post/37836552900/how-i-explained-rest-to-my-wife

Although it's a funny blog post, I think it becomes redundant. It doesn't really delve into relevant technical details.

What is REST? (if you haven't already read it, read the REST Wikipedia article): http://en.wikipedia.org/wiki/Representational_state_transfer

Repeated.

• CloudFlare WebSockets (good intro): https://blog.cloudflare.com/cloudflare-now-supports-websockets/

Updated with another relevant link -> https://developers.cloudflare.com/workers/learning/using-websockets/

I think I captured them all.

I'm not detailing the ones I added, nor the ones that are going to be re-arranged for the specific API Design Guide & Best Practices part.

[nelsonic]

@LuchoTurtle sounds good. 👌

[nelsonic]

@LuchoTurtle please open a PR with your work when you can so that you don't end the week with work in progress stuck on your laptop. 🙏