For some time now, you have been asking for a way to share a read-only view of your API design with others involved in your API project.
From now on, every Restlet Studio API will have an associated API documentation. Just open the new API settings page, click publish, and you’re good to go.
Sleek and simple API documentation, hosted by Restlet
When you put documentation into the hands of a potential API consumer, you contribute to their developer experience. Your documentation should make developers enjoy and feel good about interacting with your API.
Restlet Studio’s new documentation layout provides for an optimal reading experience by being simple and clear. The navigation bar on the left follows your progress on the right. You can filter using the widget at the top of the navigation bar. There is plenty of space and useful color coding.
Your API consumers will thank you, and will never look back to the times when you directly shared a Swagger or RAML file with them.
Choose who can see your documentation
The new API settings page brings all your API settings into one place. From here you can choose to publish your documentation, and choose from three visibility settings:
- Team: only you and your team members can view the documentation.
- Public: anyone on the web with the link can view the documentation.
- Password protected: anyone with the link and the password can view the documentation.
How to write great documentation
For the best possible impact, your documentation should meet certain criteria.
We recommend that you provide a human and friendly overview of the purpose of functionality of your API. This sort of information fits well in the description field under your API’s name.
Every one of your API’s operations should be documented in detail. Provide human-readable explanations in description fields when necessary.
It is also a good idea to explain generalities and common facts about your API in its documentation. This includes:
- Authentication: introduce the authentication scheme that you are using, and if necessary explain how the user should go about obtaining credentials for the API.
- Error handling: introduce the way you are handling errors. Are you using HTTP status codes in a standard way? Specify any additional semantics that you are giving to your error responses.
This is our first step towards helping API designers provide high quality documentation to API consumers. We’ll be listening closely to what you have to say in preparation for a follow-up release.
Feel free to have a look at the The Contacts API example.
Also, don’t forget to log in to Restlet Studio and get your new API documentation out there!