Microsoft publishes its REST API Design Guidelines

Microsoft has published  its REST API Design Guidelines to the API community.

Microsoft API guidelines sample

According to Gareth Jones, Principal API Architect, who announced its release:

“The effort got started from hearing two key points of feedback from customers:

It should be easier to get started with Microsoft APIs – Developers wanted to be able to run the curl tool against an API endpoint and get a human-readable result in just a few minutes

APIs for Microsoft cloud services should be consistent – Developers didn’t care that an API to work with an Azure virtual machine and an API to work with a user’s Office 365 documents were developed by different parts of the company, they were both from Microsoft and developers expected consistency

One of the goals of the effort was to find the right balance of detail in the guidelines. We wanted a document that sufficiently codified best practices, but was also approachable for individual contributor engineers and technical product/program managers.”

Microsoft is a member Open API Initiative, which has been spun out of Swagger.

According to Gareth Jones:

“These guidelines represent a multi-year, cross-company, collaborative process aggregating the collective experience of hundreds of engineers designing, operating, and running global scale cloud services from across Microsoft; and listening to feedback on our APIs from customers and partners.  We have attempted to incorporate those learnings along with industry best practices in the API space to create guidelines that API teams across Microsoft use on a daily basis.”

“It’s our hope that by contributing ours to the community conversation, we can add to the body of community knowledge and reusable content so that anyone can draw upon more collective knowledge when looking to set standards and guidelines within their organization.”


Writing troubleshooting topics

It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.

According to the Oasis DITA standards committee,

Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.

The user would see a topic that looks roughly like this:
Continue reading