REST API Guidelines – Real-World Examples from Swiss and Global Organizations
Designing a good REST API is less about inventing rules and more about learning from proven, production-grade systems.
Many large organizations publicly share their API guidelines or developer portals, offering valuable insight into how they handle versioning, naming, error handling, pagination, and long-term evolution.
This post collects real-world REST API guideline examples, with a special focus on Swiss organizations, followed by well-known global standards.
Use these references as inspiration, not strict rules. Every API has its own constraints, but common patterns emerge very quickly when you compare multiple sources.
Swiss REST API Guidelines and Developer Portals
Switzerland has a strong ecosystem of public institutions, banks, and tech companies that expose APIs or publish API standards. These are especially useful if you work on enterprise or public-sector projects.
| Name | Link | Comments |
|---|---|---|
| Swiss Government | https://www.bk.admin.ch/bk/en/home/digitale-transformation-ikt-lenkung/bundesarchitektur/api-architektur-bund.html | Official federal API architecture guidelines. Very useful for governance, consistency, and long-term maintainability. |
| Swiss Fintech | https://github.com/swissfintechinnovations | Collection of standards and initiatives from Swiss financial institutions. Good reference for regulated environments. |
| Swiss Post | https://developer.post.ch/en/address-web-services-rest | Concrete REST APIs with documentation and real use cases. Good example of consumer-facing APIs. |
| Zürcher Kantonal Bank (ZKB) | https://www.zkb.ch/de/lps/unternehmen/digitales-banking/api-developer-portal.html | Enterprise banking APIs with strong security and contract focus. |
| SBB (Swiss Railways) | https://developer.sbb.ch/home | Excellent developer portal with clear onboarding and API lifecycle management. |
| Zürich Open Data | https://www.zuerich.com/en/open-data-version-20 | Public open data APIs. Useful to see how discoverability and openness are handled. |
| Infomaniak | https://developer.infomaniak.com/docs/api | Modern API documentation with a pragmatic, developer-friendly approach. |
Global REST API Guidelines
The following organizations have published widely adopted REST API guidelines. Many internal company standards are inspired by these documents.
| Name | Link | Comments |
|---|---|---|
| Adidas | https://adidas.gitbook.io/api-guidelines | Clean, pragmatic guidelines with strong focus on consistency and consumer experience. |
| Atlassian | v1 , Policy | Strong emphasis on versioning, compatibility, and marketplace integrations. |
| Cisco | https://github.com/CiscoDevNet/api-design-guide | |
| https://google.aip.dev/100 | Very detailed and opinionated. Excellent for large-scale, long-lived APIs. | |
| Microsoft REST Guidelines | https://github.com/microsoft/api-guidelines/blob/master/Guidelines.md | One of the most referenced guidelines. Strong on resource modeling and HTTP semantics. |
| USA Gov | https://github.com/WhiteHouse/api-standards/blob/master/README.md#general-guidelines-for-restful-urls | |
| Zalando RESTful API Guidelines | https://opensource.zalando.com/restful-api-guidelines/ | Extremely popular in the Java ecosystem. Very concrete rules and examples. |