API Docs and REST API Docs - created from scratch | Bouncing REST API Docs ideas of an API Architect | Working in Germany?

Hello All - Before we talk about our videos in this edition, I would like to mention some insights from a great discussion on REST API Docs ideas with a real user of our docs: Al Newkirk - Al is a Senior Software Architect & API Engineering Expert Specializing in Scalable Microservice Architectures and he is based in Philadelphia.

Approaching REST API Documentation: Insights from an interaction with an API Architecture Expert

Al pinged me on linkedin for a discussion on REST APIs and Docs. And apart from answering his questions, I also was able to clarify a lot of things I was curious to know from a real power user of REST API Docs. I am thinking, going forward, we will be talking more with Al and a bunch of my friends who are into building the REST APIs and have so far guided me in my learning. Some of the highlights of my discussion with Al:

• Architects and developers typically want to know the capabilities of a REST API and how it works. Offering limited, trial authentication could make REST API testing easier.
• Even architects find the Authentication part of REST APIs challenging and can give up on REST APIs just because they hit a wall with the authentication process. The technical writers who can simplify the developer onboarding by clearly documenting the OAuth based authentication process will be meeting a critical need and adding to the bottom line of the business.
• Google does a great job in providing simplified authentication (with a #JWT that has dynamic access control - more on this later) and onboarding of new users by allowing easy testing of their APIs by a few hundred free calls. Google authentication works across their REST API landscape - from YouTube to Maps.
• When documenting REST APIs, the #APIReference alone is insufficient. Instead, developers need use cases that they can relate to and that can guide them to the REST API reference.
• Developers/architects testing the REST APIs do not prefer to test REST APIs through the documentation interface as it does NOT show the complete information exchange of the REST API call. Postman [also other tools like it] does a better job of displaying all the elements of information interchange of the request and response of a REST API call.

How code becomes a REST API - and how REST API docs are different from API Docs

If some of the above points went right above your head, our videos of this edition will help you clarify a lot of it, such as:

• What is a REST API reference and how you can make a REST API call using the REST API documentation?
• What is the difference between API and REST API documentation?
• How a piece of code becomes a REST API?
• How to create REST API docs from scratch?

The next video is actually extract from an earlier video (using an AI tool), which will be useful in the context and displays real life use cases of API Docs and REST API Docs:

Working in Germany?

Apart from this, there are some people asking me about working in Germany - starting with the job hunt part. If this topic is of an interest to a wider audience, we can include a small part about in TheContentGym newsletter.

I think The Content Gym can go much further with more participation from other members. So your feedback, contributions, thoughts are welcome. Let's take the learning to an even higher level.