How to properly describe an API?

Question

Yii

I'm going to make a web service with an open API (yii rest). What can you read about the specifications for describing the API? Any best practice, GOSTs, specifications (well, except for "make your API so that it's understandable"). Examples of well-documented APIs.
Yesterday on Habré there was an article Typical errors of API payment systems , where they already gave me a link (for which many thanks) to RestApiTutorial .
Here is something similar.

Answer 1

LinedIn has very good documentation . This is just an example of documentation.
Also read what is a resource. what is uri .... Most of the rules by which you need to form an API are built just on these principles.
Speaking of best practice, there are also HATEOAS and Json Api . than it's all good - allows you to automatically generate client code. Let's just remember that for angular.js there is a module that allows you to interact with HATEOAS easily and simply. But to be honest, I rarely came across apishki where it is used. I immediately remember that Sun (oracle) uses this business in its apishki to work with clouds.