+1000 to API First (peer review and version control for API definitions, use them as the starting point and the source of truth,. . .). The most used caveat from detractors is that you have to deal with changes but the fact is that APIs don’t change frequently. And think (and write) first about contract is always better
OAS 3.X (+ yaml) to design/define APIs and as the source of truth and documentation
Create common data models (focused on objects hierarchy) available, at least, for API developers (and common APIs?)
Provide tools/materials to work on the API workflow: templates for gathering requirements, templates/scaffolds for API definition, spectral ruleset for API guidelines compliance, Postman scripts to test requests/responses, Newman/Postman CLI + CI/CD?, . . .
Define what common policies are implemented on the API Gateway (metrics, logging, . . .). Developers don’t have to be worried about developing these features.
Focus especially on the most ambiguous aspects of REST APIs and common structures/responses for common situations
Keep today an eye in the future to support backward compatibility even if you make some changes (E.g.: When returning a collection, it is better to return a JSON object instead of an array even if you don’t need anything else today)
Define minimal documentation providers/developers must provide besides the development itself (e.g.: OAS definition, Postman collection, samples, sandbox?,. . . .)
When/how to store documentation (repo -> API Portal). To ensure a unique source of truth for every stakeholder
Not to have too many rules (API Guidelines are usually too long/complex -> +100 pages). API Guidelines adoption would be even more difficult. Who is going to read +100 pages? (split in several subdocuments? Create a summary for each stakeholder?)
It’s something to improve as an organization. At the same time there should be advantages for everybody (and a lot of work for promoters)
API Platform team, as the promoter, must be always available for providing help/assistance/advice. . .
Produce additional documentation to provide best practices, samples and some resources for API Developers/Consumers and several languages/frameworks (e.g.: https://github.com/wikimedia/mediawiki-api-demos)
Provide regular workshops to show use cases where providers and consumers can apply these rules/workflows/…. (and also to tell about updates to the API Guidelines)
API Guidelines and provided tools/materials are usually not easily accessible (they usually are hidden somewhere)
API Guidelines are too long. E.g.: Zalando API Guidelines are really good but perhaps too long (+100 pages). Not to explain which are the advantages of having API Guidelines and all the related ecosystems of tools, templates, workflows,. .
Stakeholders often don’t like changes -> Imposing vs helping (in the most cases is enough to help the very first time)
Stakeholders often don’t know an API Guidelines exist (new producers/consumers appear frequently)
Stakeholders often feel that they have to work more than before and do useless tasks when a new workflow is proposed
Stakeholders often don’t see they can save a lot of time (they don’t understand/nobody explained which advantages are provided by the API Guidelines). Everybody needs to see clear advantages in the new workflows/API Guidelines before adopting them
Stakeholders usually don’t understand how API Portal enrollment and API Authentication works (learning curve as producers and consumers)
Stakeholders don’t want/like to read too much
Sometimes we tend to spend too much energy deciding the best technical detail when several are valid (lower_snake_case vs lowerCamelCase, /users/{id} vs /user/{id}, . . .). In most cases everything is already written
Not to keep updated all the provided documentation/tools/workflow. . .
Not to communicate changes done in the API Guidelines and related tools/documentation/workflows or change them frequently
To consider everybody knows what REST means and how an API should be today
