[ { "path": "CONTRIBUTING.md", "content": "## Contributing\n\nWe welcome contributions to this guide and discussion about its\ncontents. Please open an issue or pull request on this repository to\npropose a change.\n" }, { "path": "CONTRIBUTORS.md", "content": "* Andrew Couch \n* Ben Hockey \n* Brandur \n* Brandur \n* C. T. Lin \n* David Paschich \n* Dyego Costa \n* Gordon Yeu \n* James Manning \n* Jonathan Hanson \n* Jonathan Roes \n* Karl Coelho \n* Keith Cirkel \n* Mario Vejlupek \n* Mark McGranaghan \n* Matt Haggard \n* Richard Hoberman \n* Stefano Uliari \n* Steve \n* Steven Beeckman \n* Thomas Orozco \n* Tom Christie \n* Travis Paul \n* Wesley Beary \n* Wesley Beary \n* e3 \n* geemus " }, { "path": "LANGS.md", "content": "* [English](en)\n* [Italian](it)\n" }, { "path": "LICENSE.md", "content": "## License\n\nCopyright the [project contributors](CONTRIBUTORS.md).\n\nReleased under a [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).\n" }, { "path": "README.md", "content": "# HTTP API Design Guide\n\nThis guide describes a set of HTTP+JSON API design practices, originally\nextracted from work on the [Heroku Platform API](https://devcenter.heroku.com/articles/platform-api-reference).\n\nThis guide informs additions to that API and also guides new internal\nAPIs at Heroku. We hope it’s also of interest to API designers\noutside of Heroku.\n\nOur goals here are consistency and focusing on business logic while\navoiding design bikeshedding. We’re looking for _a good, consistent,\nwell-documented way_ to design APIs, not necessarily _the only/ideal\nway_.\n\nWe assume you’re familiar with the basics of HTTP+JSON APIs and won’t\ncover all of the fundamentals of those in this guide.\n\nAvailable for online reading and in multiple formats at [gitbook](https://geemus.gitbooks.io/http-api-design).\n\nWe welcome [contributions](https://github.com/interagent/http-api-design/blob/master/CONTRIBUTING.md) to this guide.\n\nSee [Summary](en/SUMMARY.md) for Table of Contents.\n\nFor the best reading experience, we recommend reading via [GitBook](https://geemus.gitbooks.io/http-api-design).\n\n### Gitbook Translations\n * [English](https://geemus.gitbooks.io/http-api-design/content/en/index.html)\n * [Italian](https://geemus.gitbooks.io/http-api-design/content/it/index.html) (based on [f12db3e](https://github.com/interagent/http-api-design/commit/f12db3e)), by [@diegomariani](https://github.com/diegomariani/)\n * [Simplified Chinese](https://one-programmer.github.io/docs/http-api-design/) (based on [40d114b](https://github.com/interagent/http-api-design/commit/40d114b6efbc60b84c804dbe7ad34b0d5e155a49)), by [@ZhangBohan](https://github.com/ZhangBohan/)\n\n### Git Translations\n * [Korean](https://github.com/yoondo/http-api-design) (based on [f38dba6](https://github.com/interagent/http-api-design/commit/f38dba6fd8e2b229ab3f09cd84a8828987188863)), by [@yoondo](https://github.com/yoondo/)\n * [Portuguese](https://github.com/Gutem/http-api-design/) (based on [fba98f08b5](https://github.com/interagent/http-api-design/commit/fba98f08b50acbb08b7b30c012a6d0ca795e29ee)), by [@Gutem](https://github.com/Gutem/)\n * [Simplified Chinese](https://github.com/ZhangBohan/http-api-design-ZH_CN) (based on [337c4a0](https://github.com/interagent/http-api-design/commit/337c4a05ad08f25c5e232a72638f063925f3228a)), by [@ZhangBohan](https://github.com/ZhangBohan/)\n * [Spanish](https://github.com/jmnavarro/http-api-design) (based on [2a74f45](https://github.com/interagent/http-api-design/commit/2a74f45b9afaf6c951352f36c3a4e1b0418ed10b)), by [@jmnavarro](https://github.com/jmnavarro/)\n * [Traditional Chinese](https://github.com/kcyeu/http-api-design) (based on [232f8dc](https://github.com/interagent/http-api-design/commit/232f8dc6a941d0b25136bf64998242dae5575f66)), by [@kcyeu](https://github.com/kcyeu/)\n * [Turkish](https://github.com/hkulekci/http-api-design/tree/master/tr) (based on [c03842f](https://github.com/interagent/http-api-design/commit/c03842fda80261e82860f6dc7e5ccb2b5d394d51)), by [@hkulekci](https://github.com/hkulekci/)\n" }, { "path": "en/README.md", "content": "# HTTP API Design Guide\n\nThis guide describes a set of HTTP+JSON API design practices, originally\nextracted from work on the [Heroku Platform API](https://devcenter.heroku.com/articles/platform-api-reference).\n\nThis guide informs additions to that API and also guides new internal\nAPIs at Heroku. We hope it’s also of interest to API designers\noutside of Heroku.\n\nOur goals here are consistency and focusing on business logic while\navoiding design bikeshedding. We’re looking for _a good, consistent,\nwell-documented way_ to design APIs, not necessarily _the only/ideal\nway_.\n\nWe assume you’re familiar with the basics of HTTP+JSON APIs and won’t\ncover all of the fundamentals of those in this guide.\n\nAvailable for online reading and in multiple formats at [gitbook](https://geemus.gitbooks.io/http-api-design/).\n\nWe welcome [contributions](https://github.com/interagent/http-api-design/blob/master/CONTRIBUTING.md) to this guide.\n\nSee [Summary](https://github.com/interagent/http-api-design/blob/master/en/SUMMARY.md) for Table of Contents.\n\n### Translations\n * [Portuguese version](https://github.com/Gutem/http-api-design/) (based on [fba98f08b5](https://github.com/interagent/http-api-design/commit/fba98f08b50acbb08b7b30c012a6d0ca795e29ee)), by [@Gutem](https://github.com/Gutem/)\n * [Spanish version](https://github.com/jmnavarro/http-api-design) (based on [2a74f45](https://github.com/interagent/http-api-design/commit/2a74f45b9afaf6c951352f36c3a4e1b0418ed10b)), by [@jmnavarro](https://github.com/jmnavarro/)\n * [Korean version](https://github.com/yoondo/http-api-design) (based on [f38dba6](https://github.com/interagent/http-api-design/commit/f38dba6fd8e2b229ab3f09cd84a8828987188863)), by [@yoondo](https://github.com/yoondo/)\n * [Simplified Chinese version](https://github.com/ZhangBohan/http-api-design-ZH_CN) (based on [337c4a0](https://github.com/interagent/http-api-design/commit/337c4a05ad08f25c5e232a72638f063925f3228a)), by [@ZhangBohan](https://github.com/ZhangBohan/)\n * [Traditional Chinese version](https://github.com/kcyeu/http-api-design) (based on [232f8dc](https://github.com/interagent/http-api-design/commit/232f8dc6a941d0b25136bf64998242dae5575f66)), by [@kcyeu](https://github.com/kcyeu/)\n * [Turkish version](https://github.com/hkulekci/http-api-design/tree/master/tr) (based on [c03842f](https://github.com/interagent/http-api-design/commit/c03842fda80261e82860f6dc7e5ccb2b5d394d51)), by [@hkulekci](https://github.com/hkulekci/)\n\n" }, { "path": "en/SUMMARY.md", "content": "# HTTP API Design Guide\n\n* [Foundations](foundations/README.md)\n * [Separate Concerns](foundations/separate-concerns.md)\n * [Require Secure Connections](foundations/require-secure-connections.md)\n * [Require Versioning in the Accepts Header](foundations/require-versioning-in-the-accepts-header.md)\n * [Support ETags for Caching](foundations/support-etags-for-caching.md)\n * [Provide Request-Ids for Introspection](foundations/provide-request-ids-for-introspection.md)\n * [Divide Large Responses Across Requests with Ranges](foundations/divide-large-responses-across-requests-with-ranges.md)\n* [Requests](requests/README.md)\n * [Accept serialized JSON in request bodies](requests/accept-serialized-json-in-request-bodies.md)\n * [Resource names](requests/resource-names.md)\n * [Actions](requests/actions.md)\n * [Use consistent path formats](requests/use-consistent-path-formats.md)\n * [Downcase paths and attributes](requests/downcase-paths-and-attributes.md)\n * [Support non-id dereferencing for convenience](requests/support-non-id-dereferencing-for-convenience.md)\n * [Minimize path nesting](requests/minimize-path-nesting.md)\n* [Responses](responses/README.md)\n * [Return appropriate status codes](responses/return-appropriate-status-codes.md)\n * [Provide full resources where available](responses/provide-full-resources-where-available.md)\n * [Provide resource (UU)IDs](responses/provide-resource-uuids.md)\n * [Provide standard timestamps](responses/provide-standard-timestamps.md)\n * [Provide standard response types](responses/provide-standard-response-types.md)\n * [Use UTC times formatted in ISO8601](responses/use-utc-times-formatted-in-iso8601.md)\n * [Nest foreign key relations](responses/nest-foreign-key-relations.md)\n * [Generate structured errors](responses/generate-structured-errors.md)\n * [Show rate limit status](responses/show-rate-limit-status.md)\n * [Keep JSON minified in all responses](responses/keep-json-minified-in-all-responses.md)\n* [Artifacts](artifacts/README.md)\n * [Provide machine-readable JSON schema](artifacts/provide-machine-readable-json-schema.md)\n * [Provide human-readable docs](artifacts/provide-human-readable-docs.md)\n * [Provide executable examples](artifacts/provide-executable-examples.md)\n * [Describe stability](artifacts/describe-stability.md)\n" }, { "path": "en/artifacts/README.md", "content": "### Artifacts\n\nThe Artifacts section describes the physical objects we use to manage and\ndiscuss API designs and patterns.\n" }, { "path": "en/artifacts/describe-stability.md", "content": "#### Describe stability\n\nDescribe the stability of your API or its various endpoints according to\nits maturity and stability, e.g. with prototype/development/production\nflags.\n\nSee the [Heroku API compatibility policy](https://devcenter.heroku.com/articles/api-compatibility-policy)\nfor a possible stability and change management approach.\n\nOnce your API is declared production-ready and stable, do not make\nbackwards incompatible changes within that API version. If you need to\nmake backwards-incompatible changes, create a new API with an\nincremented version number.\n" }, { "path": "en/artifacts/provide-executable-examples.md", "content": "#### Provide executable examples\n\nProvide executable examples that users can type directly into their\nterminals to see working API calls. To the greatest extent possible,\nthese examples should be usable verbatim, to minimize the amount of\nwork a user needs to do to try the API, e.g.:\n\n```bash\n$ export TOKEN=... # acquire from dashboard\n$ curl -is https://$TOKEN@service.com/users\n```\n\nIf you use [prmd](https://github.com/interagent/prmd) to generate Markdown\ndocs, you will get examples for each endpoint for free.\n" }, { "path": "en/artifacts/provide-human-readable-docs.md", "content": "#### Provide human-readable docs\n\nProvide human-readable documentation that client developers can use to\nunderstand your API.\n\nIf you create a schema with prmd as described above, you can easily\ngenerate Markdown docs for all endpoints with `prmd doc`.\n\nIn addition to endpoint details, provide an API overview with\ninformation about:\n\n* Authentication, including acquiring and using authentication tokens.\n* API stability and versioning, including how to select the desired API\n version.\n* Common request and response headers.\n* Error serialization format.\n* Examples of using the API with clients in different languages.\n" }, { "path": "en/artifacts/provide-machine-readable-json-schema.md", "content": "#### Provide machine-readable JSON schema\n\nProvide a machine-readable schema to exactly specify your API. Use\n[prmd](https://github.com/interagent/prmd) to manage your schema, and ensure\nit validates with `prmd verify`.\n" }, { "path": "en/foundations/README.md", "content": "### Foundations\n\nThe Foundations section outlines the design principles upon which the rest of\nthe guide builds.\n" }, { "path": "en/foundations/divide-large-responses-across-requests-with-ranges.md", "content": "#### Divide Large Responses Across Requests with Ranges\n\nLarge responses should be broken across multiple requests using `Range` headers\nto specify when more data is available and how to retrieve it. See the\n[Heroku Platform API discussion of Ranges](https://devcenter.heroku.com/articles/platform-api-reference#ranges)\nfor the details of request and response headers, status codes, limits,\nordering, and iteration.\n" }, { "path": "en/foundations/provide-request-ids-for-introspection.md", "content": "#### Provide Request-Ids for Introspection\n\nInclude a `Request-Id` header in each API response, populated with a\nUUID value. By logging these values on the client, server and any backing\nservices, it provides a mechanism to trace, diagnose and debug requests.\n" }, { "path": "en/foundations/require-secure-connections.md", "content": "#### Require Secure Connections\n\nRequire secure connections with TLS to access the API, without exception.\nIt’s not worth trying to figure out or explain when it is OK to use TLS\nand when it’s not. Just require TLS for everything.\n\nIdeally, simply reject any non-TLS requests by not responding to requests for\nhttp or port 80 to avoid any insecure data exchange. In environments where this\nis not possible, respond with `403 Forbidden`.\n\nRedirects are discouraged since they allow sloppy/bad client behaviour without\nproviding any clear gain. Clients that rely on redirects double up on\nserver traffic and render TLS useless since sensitive data will already\n have been exposed during the first call.\n" }, { "path": "en/foundations/require-versioning-in-the-accepts-header.md", "content": "#### Require Versioning in the Accepts Header\n\nVersioning and the transition between versions can be one of the more\nchallenging aspects of designing and operating an API. As such, it is best to\nstart with some mechanisms in place to mitigate this from the start.\n\nTo prevent surprise, breaking changes to users, it is best to require a version\nbe specified with all requests. Default versions should be avoided as they are\nvery difficult, at best, to change in the future.\n\nIt is best to provide version specification in the headers, with other\nmetadata, using the `Accept` header with a custom content type, e.g.:\n\n```\nAccept: application/vnd.heroku+json; version=3\n```\n" }, { "path": "en/foundations/separate-concerns.md", "content": "#### Separate Concerns\n\nKeep things simple while designing by separating the concerns between the\ndifferent parts of the request and response cycle. Keeping simple rules here\nallows for greater focus on larger and harder problems.\n\nRequests and responses will be made to address a particular resource or\ncollection. Use the path to indicate identity, the body to transfer the\ncontents and headers to communicate metadata. Query params may be used as a\nmeans to pass header information also in edge cases, but headers are preferred\nas they are more flexible and can convey more diverse information.\n" }, { "path": "en/foundations/support-etags-for-caching.md", "content": "#### Support ETags for Caching\n\nInclude an `ETag` header in all responses, identifying the specific\nversion of the returned resource. This allows users to cache resources\nand use requests with this value in the `If-None-Match` header to determine\nif the cache should be updated.\n" }, { "path": "en/requests/README.md", "content": "### Requests\n\nThe Requests section provides an overview of patterns for API requests.\n" }, { "path": "en/requests/accept-serialized-json-in-request-bodies.md", "content": "#### Accept serialized JSON in request bodies\n\nAccept serialized JSON on `PUT`/`PATCH`/`POST` request bodies, either\ninstead of or in addition to form-encoded data. This creates symmetry\nwith JSON-serialized response bodies, e.g.:\n\n```bash\n$ curl -X POST https://service.com/apps \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"demoapp\"}'\n\n{\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"name\": \"demoapp\",\n \"owner\": {\n \"email\": \"username@example.com\",\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\"\n },\n ...\n}\n```\n" }, { "path": "en/requests/actions.md", "content": "##### Actions\n\nPrefer endpoint configurations that don’t require special actions. In cases\nwhere actions are needed, clearly delineate them with the `actions` prefix:\n\n```\n/resources/:resource/actions/:action\n```\n\ne.g. to stop a particular run:\n\n```\n/runs/{run_id}/actions/stop\n```\n\nActions on collections should also be minimized. Where needed, they should use\na top-level actions delineation to avoid namespace conflicts and clearly show\nthe scope of action:\n\n```\n/actions/:action/resources\n```\n\ne.g. to restart all servers:\n\n```\n/actions/restart/servers\n```\n" }, { "path": "en/requests/downcase-paths-and-attributes.md", "content": "#### Downcase paths and attributes\n\nUse downcased and dash-separated path names, for alignment with\nhostnames, e.g:\n\n```\nservice-api.com/users\nservice-api.com/app-setups\n```\n\nDowncase attributes as well, but use underscore separators so that\nattribute names can be typed without quotes in JavaScript, e.g.:\n\n```\nservice_class: \"first\"\n```\n" }, { "path": "en/requests/minimize-path-nesting.md", "content": "#### Minimize path nesting\n\nIn data models with nested parent/child resource relationships, paths\nmay become deeply nested, e.g.:\n\n```\n/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}\n```\n\nLimit nesting depth by preferring to locate resources at the root\npath. Use nesting to indicate scoped collections. For example, for the\ncase above where a dyno belongs to an app belongs to an org:\n\n```\n/orgs/{org_id}\n/orgs/{org_id}/apps\n/apps/{app_id}\n/apps/{app_id}/dynos\n/dynos/{dyno_id}\n```\n" }, { "path": "en/requests/resource-names.md", "content": "##### Resource names\n\nUse the plural version of a resource name unless the resource in question is a singleton within the system (for example, the overall status of the system might be `/status`). This keeps it consistent in the way you refer to particular resources.\n" }, { "path": "en/requests/support-non-id-dereferencing-for-convenience.md", "content": "#### Support non-id dereferencing for convenience\n\nIn some cases it may be inconvenient for end-users to provide IDs to\nidentify a resource. For example, a user may think in terms of a Heroku\napp name, but that app may be identified by a UUID. In these cases you\nmay want to accept both an id or name, e.g.:\n\n```bash\n$ curl https://service.com/apps/{app_id_or_name}\n$ curl https://service.com/apps/97addcf0-c182\n$ curl https://service.com/apps/www-prod\n```\n\nDo not accept only names to the exclusion of IDs.\n" }, { "path": "en/requests/use-consistent-path-formats.md", "content": "#### Use consistent path formats\n" }, { "path": "en/responses/README.md", "content": "### Responses\n\nThe Responses section provides an overview of patterns for API responses.\n" }, { "path": "en/responses/generate-structured-errors.md", "content": "#### Generate structured errors\n\nGenerate consistent, structured response bodies on errors. Include a\nmachine-readable error `id`, a human-readable error `message`, and\noptionally a `url` pointing the client to further information about the\nerror and how to resolve it, e.g.:\n\n```\nHTTP/1.1 429 Too Many Requests\n```\n\n```json\n{\n \"id\": \"rate_limit\",\n \"message\": \"Account reached its API rate limit.\",\n \"url\": \"https://docs.service.com/rate-limits\"\n}\n```\n\nDocument your error format and the possible error `id`s that clients may\nencounter.\n" }, { "path": "en/responses/keep-json-minified-in-all-responses.md", "content": "#### Keep JSON minified in all responses\n\nExtra whitespace adds needless response size to requests, and many\nclients for human consumption will automatically \"prettify\" JSON\noutput. It is best to keep JSON responses minified e.g.:\n\n```json\n{\"beta\":false,\"email\":\"alice@heroku.com\",\"id\":\"01234567-89ab-cdef-0123-456789abcdef\",\"last_login\":\"2012-01-01T12:00:00Z\",\"created_at\":\"2012-01-01T12:00:00Z\",\"updated_at\":\"2012-01-01T12:00:00Z\"}\n```\n\nInstead of e.g.:\n\n```json\n{\n \"beta\": false,\n \"email\": \"alice@heroku.com\",\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"last_login\": \"2012-01-01T12:00:00Z\",\n \"created_at\": \"2012-01-01T12:00:00Z\",\n \"updated_at\": \"2012-01-01T12:00:00Z\"\n}\n```\n\nYou may consider optionally providing a way for clients to retrieve\nmore verbose response, either via a query parameter (e.g. `?pretty=true`)\nor via an `Accept` header param (e.g.\n`Accept: application/vnd.heroku+json; version=3; indent=4;`).\n" }, { "path": "en/responses/nest-foreign-key-relations.md", "content": "#### Nest foreign key relations\n\nSerialize foreign key references with a nested object, e.g.:\n\n```javascript\n{\n \"name\": \"service-production\",\n \"owner\": {\n \"id\": \"5d8201b0...\"\n },\n // ...\n}\n```\n\nInstead of e.g.:\n\n```javascript\n{\n \"name\": \"service-production\",\n \"owner_id\": \"5d8201b0...\",\n // ...\n}\n```\n\nThis approach makes it possible to inline more information about the\nrelated resource without having to change the structure of the response\nor introduce more top-level response fields, e.g.:\n\n```javascript\n{\n \"name\": \"service-production\",\n \"owner\": {\n \"id\": \"5d8201b0...\",\n \"email\": \"alice@heroku.com\"\n },\n // ...\n}\n```\n\nWhen nesting foreign key relations, use either the full record or just the foreign keys. Providing a subset of fields can lead to surprises and confusion, makes inconsistencies between different actions and endpoints more likely.\n\nTo avoid inconsistency and confusion, serialize either:\n- **foreign keys** only - values the full record can be looked up with, like `id`, `slug`, `email`.\n- **full record**, all fields (this would be an \"embedded record\")\n" }, { "path": "en/responses/provide-full-resources-where-available.md", "content": "#### Provide full resources where available\n\nProvide the full resource representation (i.e. the object with all\nattributes) whenever possible in the response. Always provide the full\nresource on 200 and 201 responses, including `PUT`/`PATCH` and `DELETE`\nrequests, e.g.:\n\n```bash\n$ curl -X DELETE \\\n https://service.com/apps/1f9b/domains/0fd4\n\nHTTP/1.1 200 OK\nContent-Type: application/json;charset=utf-8\n...\n{\n \"created_at\": \"2012-01-01T12:00:00Z\",\n \"hostname\": \"subdomain.example.com\",\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"updated_at\": \"2012-01-01T12:00:00Z\"\n}\n```\n\n202 responses will not include the full resource representation,\ne.g.:\n\n```bash\n$ curl -X DELETE \\\n https://service.com/apps/1f9b/dynos/05bd\n\nHTTP/1.1 202 Accepted\nContent-Type: application/json;charset=utf-8\n...\n{}\n```\n" }, { "path": "en/responses/provide-resource-uuids.md", "content": "#### Provide resource (UU)IDs\n\nGive each resource an `id` attribute by default. Use UUIDs unless you\nhave a very good reason not to. Don’t use IDs that won’t be globally\nunique across instances of the service or other resources in the\nservice, especially auto-incrementing IDs.\n\nRender UUIDs in downcased `8-4-4-4-12` format, e.g.:\n\n```\n\"id\": \"01234567-89ab-cdef-0123-456789abcdef\"\n```\n" }, { "path": "en/responses/provide-standard-response-types.md", "content": "#### Provide standard response types\n\nThis document describes the acceptable values for each of JSON's basic data\ntypes.\n\n### String\n\n* Acceptable values:\n * string\n * `null`\n\ne.g:\n\n```javascript\n[\n {\n \"description\": \"very descriptive description.\"\n },\n {\n \"description\": null\n },\n]\n```\n\n### Boolean\n\n* Acceptable values:\n * true\n * false\n\ne.g:\n\n```javascript\n[\n {\n \"provisioned_licenses\": true\n },\n {\n \"provisioned_licenses\": false\n },\n]\n```\n\n### Number\n\n* Acceptable values:\n * number\n * `null`\n\nNote: some JSON parsers will return numbers with a precision of over 15\ndecimal places as strings. If you need precision greater than 15 decimals,\nalways return a string for that value. If not, convert those strings to numbers\nso that consumers of the API always know what value type to expect.\n\ne.g:\n\n```javascript\n[\n {\n \"average\": 27.123\n },\n {\n \"average\": 12.123456789012\n },\n]\n```\n\n### Array\n\n* Acceptable values:\n * array\n\nNote: Return an empty array rather than `NULL` when there are no values in the\narray.\n\ne.g:\n\n```javascript\n[\n {\n \"child_ids\": [1, 2, 3, 4],\n },\n {\n \"child_ids\": [],\n }\n]\n```\n\n### Object\n\n* Acceptable values:\n * object\n * null\n\ne.g:\n\n```javascript\n[\n {\n \"name\": \"service-production\",\n \"owner\": {\n \"id\": \"5d8201b0...\"\n }\n },\n {\n \"name\": \"service-staging\",\n \"owner\": null\n }\n]\n```\n" }, { "path": "en/responses/provide-standard-timestamps.md", "content": "#### Provide standard timestamps\n\nProvide `created_at` and `updated_at` timestamps for resources by default,\ne.g:\n\n```javascript\n{\n // ...\n \"created_at\": \"2012-01-01T12:00:00Z\",\n \"updated_at\": \"2012-01-01T13:00:00Z\",\n // ...\n}\n```\n\nThese timestamps may not make sense for some resources, in which case\nthey can be omitted.\n" }, { "path": "en/responses/return-appropriate-status-codes.md", "content": "#### Return appropriate status codes\n\nReturn appropriate HTTP status codes with each response. Successful\nresponses should be coded according to this guide:\n\n* `200`: Request succeeded for a `GET`, `POST`, `DELETE`, or `PATCH` call that\n completed synchronously, or a `PUT` call that synchronously updated an\n existing resource\n* `201`: Request succeeded for a `POST`, or `PUT` call that synchronously\n created a new resource. It is also best practice to provide a 'Location'\n header pointing to the newly created resource. This is particularly useful\n in the `POST` context as the new resource will have a different URL than the\n original request.\n* `202`: Request accepted for a `POST`, `PUT`, `DELETE`, or `PATCH` call that\n will be processed asynchronously\n* `206`: Request succeeded on `GET`, but only a partial response\n returned: see [above on ranges](../foundations/divide-large-responses-across-requests-with-ranges.md)\n\nPay attention to the use of authentication and authorization error codes:\n\n* `401 Unauthorized`: Request failed because user is not authenticated\n* `403 Forbidden`: Request failed because user does not have authorization to access a specific resource\n\nReturn suitable codes to provide additional information when there are errors:\n\n* `422 Unprocessable Entity`: Your request was understood, but contained invalid parameters\n* `429 Too Many Requests`: You have been rate-limited, retry later\n* `500 Internal Server Error`: Something went wrong on the server, check status site and/or report the issue\n\nRefer to the [HTTP response code spec](https://tools.ietf.org/html/rfc7231#section-6)\nfor guidance on status codes for user error and server error cases.\n" }, { "path": "en/responses/show-rate-limit-status.md", "content": "#### Show rate limit status\n\nRate limit requests from clients to protect the health of the service\nand maintain high service quality for other clients. You can use a\n[token bucket algorithm](http://en.wikipedia.org/wiki/Token_bucket) to\nquantify request limits.\n\nReturn the remaining number of request tokens with each request in the\n`RateLimit-Remaining` response header.\n" }, { "path": "en/responses/use-utc-times-formatted-in-iso8601.md", "content": "#### Use UTC times formatted in ISO8601\n\nAccept and return times in UTC only. Render times in ISO8601 format,\ne.g.:\n\n```\n\"finished_at\": \"2012-01-01T12:00:00Z\"\n```\n" }, { "path": "it/README.md", "content": "# Guida alla progettazione di API HTTP\n\nQuesta guida descrive un insieme di pratiche per la progettazione di API HTTP+JSON, originariamente tratte dal lavoro sulle [API della Piattaforma Heroku](https://devcenter.heroku.com/articles/platform-api-reference).\n\nLa guida serve come riferimento sia per le modifiche alle API correnti che per lo sviluppo di nuove API all'interno di Heroku; speriamo sia di interesse per tutti gli API designer anche al di fuori di Heroku.\n\nI nostri obiettivi sono la coerenza ed il focalizzarsi sulla logica di business, evitando inutili perdite di tempo durante la progettazione. Perseguiamo un _metodo ottimale, coerente e ben documentato_ per progettare API, che non sia necessariamente _l'unico e solo modo ideale_ di farlo.\n\nDiamo per scontato che tu abbia già familiarità con i principi alla base delle API HTTP+JSON, quindi questa guida non comprende tutta la parte teorica fondamentale sull'argomento.\n\nLa guida è disponibile in diversi formati a questo link [gitbook](https://www.gitbook.com/read/book/geemus/http-api-design)\n\nAccettiamo volentieri [contributi](../CONTRIBUTING.md) alla guida.\n\nVai al [Sommario](SUMMARY.md) per l'indice dei contenuti.\n\n### Traduzioni\n * [Versione in Portoghese](https://github.com/Gutem/http-api-design/) (based on [fba98f08b5](https://github.com/interagent/http-api-design/commit/fba98f08b50acbb08b7b30c012a6d0ca795e29ee)), di [@Gutem](https://github.com/Gutem/)\n * [Versione in Spagnolo](https://github.com/jmnavarro/http-api-design) (based on [2a74f45](https://github.com/interagent/http-api-design/commit/2a74f45b9afaf6c951352f36c3a4e1b0418ed10b)), di [@jmnavarro](https://github.com/jmnavarro/)\n * [Versione in Coreano](https://github.com/yoondo/http-api-design) (based on [f38dba6](https://github.com/interagent/http-api-design/commit/f38dba6fd8e2b229ab3f09cd84a8828987188863)), di [@yoondo](https://github.com/yoondo/)\n * [Versione in Cinese Semplificato](https://github.com/ZhangBohan/http-api-design-ZH_CN) (based on [337c4a0](https://github.com/interagent/http-api-design/commit/337c4a05ad08f25c5e232a72638f063925f3228a)), di [@ZhangBohan](https://github.com/ZhangBohan/)\n * [Versione in Cinese Tradizionale](https://github.com/kcyeu/http-api-design) (based on [232f8dc](https://github.com/interagent/http-api-design/commit/232f8dc6a941d0b25136bf64998242dae5575f66)), di [@kcyeu](https://github.com/kcyeu/)\n * [Versione in Turco](https://github.com/hkulekci/http-api-design/tree/master/tr) (based on [c03842f](https://github.com/interagent/http-api-design/commit/c03842fda80261e82860f6dc7e5ccb2b5d394d51)), di [@hkulekci](https://github.com/hkulekci/)\n\n" }, { "path": "it/SUMMARY.md", "content": "# Guida alla progettazione delle API HTTP\n\n* [Fondamenti](SUMMARY.md#fondamenti)\n * [Concetti separati](SUMMARY.md#concetti-separati)\n * [Utlizza una connessione sicura (TLS)](SUMMARY.md#utlizza-una-connessione-sicura-(tls))\n * [Richiedi il versioning negli Accept Headers](SUMMARY.md#richiedi-il-versioning-negli-accept-headers)\n * [Supporta ETag per il caching](SUMMARY.md#supporta-etag-per-il-caching)\n * [Fornisci un parametro Request-Ids per l'analisi](SUMMARY.md#fornisci-un-parametro-request-ids-per-lanalisi)\n * [Dividi risposte molto lunghe in piu richieste con range](SUMMARY.md#dividi-risposte-molto-lunghe-in-piu-richieste-con-range)\n* [Richieste](SUMMARY.md#richieste)\n * [Accetta JSON serializzato nei corpi delle richieste](SUMMARY.md#accetta-json-serializzato-nei-corpi-delle-richieste)\n * [Nomi delle risorse](SUMMARY.md#nomi-delle-risorse)\n * [Azioni](SUMMARY.md#azioni)\n * [Usa un formato consistente per i percorsi (path)](SUMMARY.md#usa-un-formato-consistente-per-i-percorsi-path)\n * [Caratteri minuscoli per percorsi e attributi](SUMMARY.md#caratteri-minuscoli-per-percorsi-e-attributi)\n * [Supporta anche riferimenti non-id per comodita](SUMMARY.md#supporta-anche-riferimenti-non-id-per-comodita)\n * [Minimizza annidamento dei percorsi](SUMMARY.md#minimizza-annidamento-dei-percorsi)\n* [Risposte](SUMMARY.md#risposte)\n * [Ritorna sempre un codice di stato appropriato](SUMMARY.md#ritorna-sempre-un-codice-di-stato-appropriato)\n * [Fornisci le risorse interamente, quando possibile](SUMMARY.md#fornisci-le-risorse-interamente-quando-possibile)\n * [Fornisci gli (UU)IDs delle risorse](SUMMARY.md#fornisci-gli-uuids-delle-risorse)\n * [Fornisci dei timestamps standard](SUMMARY.md#fornisci-dei-timestamps-standard)\n * [Usa date in formato UTC formattate in ISO8601](SUMMARY.md#usa-date-in-formato-utc-formattate-in-iso8601)\n * [Annida relazioni tramite le chiavi esterne (foreign-key)](SUMMARY.md#annida-relazioni-tramite-le-chiavi-esterne-foreign-key)\n * [Genera errori strutturati](SUMMARY.md#genera-errori-strutturati)\n * [Visualizza lo stato del limite delle richieste](SUMMARY.md#visualizza-lo-stato-del-limite-delle-richieste)\n * [Mantieni il JSON minimizzato in tutte le risposte](SUMMARY.md#mantieni-il-json-minimizzato-in-tutte-le-risposte)\n* [Artefatti](SUMMARY.md#artefatti)\n * [Fornisci uno schema JSON interpretabile](SUMMARY.md#fornisci-uno-schema-json-interpretabile)\n * [Fornisci una documentazione comprensibile allo sviluppatore](SUMMARY.md#fornisci-una-documentazione-comprensibile-allo-sviluppatore)\n * [Fornisci degli esempi](SUMMARY.md#fornisci-degli-esempi)\n * [Specifica la stabilità della tua API](SUMMARY.md#specifica-la-stabilita-della-tua-api)\n\n### Fondamenti\n\nQuesta sezione illustra i principi di progettazione, sui quali si basa questa guida\n\n\n#### Concetti separati\n\nStruttura i componenti in maniera semplice mentre li progetti, separando i concetti tra le varie parti del ciclo di richiesta e risposta. Mantenendo la semplicita sui componenti, avrai possibilità di focalizzarti di più su problemi più grandi e più difficili da risolvere.\n\nLa richiesta e la risposta saranno fatte in modo da gestire una particolare risorsa oppure una loro collezione. Usa il percorso (path) per indicare un'identità, il body per trasferire il contenuto e gli headers per comunicare dati aggiuntivi (metadata). I parametri di query passati nell'url, possono essere usati come alternativa agli headers, solo in rari casi. Gli headers sono sempre preferiti, perche permettono più flessibilità e permettono di inviare informazioni più dettagliate.\n\n#### Utlizza una connessione sicura (TLS)\n\nRichiedi una connessione sicura con protocollo TLS per accedere alle APIs, senza eccezioni.\nNon importa cercare di capire quando è opportuno usare TLS oppure quando non lo è. Semplicemente richiedila sempre.\n\nIdealmente, puoi rifiutare qualsiasi richiesta che non sia fatta utilizzando il protocollo TLS, per evitare scambi di dati ed informazioni non sicuri. Nel caso in cui non possa gestire questo tipo di regola, basta rispondere con un `403 Forbidden`.\n\nI redirects sono sconsigliati in quanto non rappresentano un buon approccio. I clients che si imbattono in molti redirects, raddoppiano il traffico sul server e rendono pressocche inutile il protocollo TLS, in quanto le informazioni sensibili vengono esplicitate durante la prima chiamata http\n\n#### Richiedi il versioning negli Accept Headers\n\nUn sistema di versioning e transizione tra le versioni può essere uno degli aspetti più difficili da progettare e realizzare nelle tue REST API. Proprio per questo, è meglio cominciare con alcuni accorgimenti che ci aiuteranno a mitigare questo tipo di problemi sin da subito.\n\nPer evitare sorprese, cambiamenti bruschi agli utenti, è certamente buona norma richiedere di specificare la versione delle APIs in tutte le richieste. Il meccanismo di impostare una versione di default dovrebbe essere evitato, in quanto è molto difficile da cambiare in futuro.\n\nL'approccio migliore sarebbe quello di specificare la versione negli headers http, con altri metadata, utilizzando per esempio `Accept` header con un `Content-Type` specifico, es:\n\n```\nAccept: application/vnd.heroku+json; version=3\n```\n\n\n#### Supporta ETag per il caching\n\nIncludi un header `ETag` in tutte le risposte, identificando la specifica versione della risorsa restituita.\nQuesto permetterà gli utenti di aggiungere alla cache le risorse e fare delle richieste con questo valore \naggiungendo un `If-None-Match` header per determinare se la cache debba essere aggiornata o meno.\n\n\n#### Fornisci un parametro Request-Ids per l'analisi\n\nIncludi un parametro `Request-Id` nell'header per ogni risposta della API, popolato con un valore UUID.\nFacendo un log di questi valori nel client, server ed altri servizi ausiliari, è possibile ottenere un meccanismo di tracciabilità, diagnosi e debug delle richieste.\n\n#### Dividi risposte molto lunghe in piu richieste con range\n\nRisposte molto grandi, dovrebbero essere divise in più richieste usando un header `Range` per specificare quando più dati sono disponibili e come recuperarli. Dai un'occhiata alla documentazione [Heroku Platform API discussion of Ranges](https://devcenter.heroku.com/articles/platform-api-reference#ranges) per i dettagli degli headers delle richieste e delle risposte, codici di stato, limiti, ordinamenti e iterazioni\n\n### Richieste\n\nLa sezione delle richieste fornisce una panoramica della struttura per le richieste API.\n\n#### Accetta JSON serializzato nei corpi delle richieste\n\nAccetta JSON serializzato nei corpi delle richieste `PUT`/`PATCH`/`POST` oppure in aggiunta ai dati form-encoded. Questo crea simmetria con i il corpo JSON serializzato delle risposte, es:\n\n```bash\n$ curl -X POST https://service.com/apps \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"demoapp\"}'\n\n{\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"name\": \"demoapp\",\n \"owner\": {\n \"email\": \"username@example.com\",\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\"\n },\n ...\n}\n```\n\n##### Nomi delle risorse\n\nUsa il nome plurale di un nome di risorsa a meno che la risorsa in questione non sia un nome singolare relativo al sistema stesso (per esempio in alcuni sistemi un determinato utente può avere un solo account). Questo mantiene la consistenza quando ti riferisci alle risorse\n\n##### Azioni\n\nPreferisci dei layout per gli endpoint che non prevedono azioni speciali per una determinata risorsa.\nNel caso in cui sia necessario prevedere la possibilità di azioni speciali, specificale sotto un prefisso standard come `actions`, per definirle in modo chiaro:\n\n```\n/resources/:resource/actions/:action\n```\n\nes.\n\n```\n/runs/{run_id}/actions/stop\n```\n\n#### Usa un formato consistente per i percorsi (path)\n\n#### Caratteri minuscoli per percorsi e attributi\n\nUsa dei percorsi in minuscolo e separati da trattini, per congruenza con gli hostnames, es:\n\n```\nservice-api.com/users\nservice-api.com/app-setups\n```\n\nAnche per gli attributi utilizza il minuscolo, ma separando le parole con un underscore, in modo che possano essere scritti\nsenza l'utilizzo delle virgolette in JavaScript, es:\n\n```\nservice_class: \"first\"\n```\n\n#### Supporta anche riferimenti non-id per comodita\n\nIn alcuni casi potrebbe essere scomodo per gli utenti finali, fornire ID per \nidentificare una risorsa. Per esempio, un utente può pensare in termini del nome di una app, ma questa app può essere identificata tramite un UUID. In questi casi, potresti prevedere di accettare entrambi: ID e nome, es:\n\n```bash\n$ curl https://service.com/apps/{app_id_or_name}\n$ curl https://service.com/apps/97addcf0-c182\n$ curl https://service.com/apps/www-prod\n```\nNon accettare comunque soltanto un nome, senza la possibilità di specificare un ID\n\n#### Minimizza annidamento dei percorsi\n\nNei model che rappresentano i nostri dati con le relazioni padre/figlio annidate, i percorsi possono diventare\nveramente molto lunghi, es:\n\n```\n/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}\n```\n\nLimita l'annidamento, preferendo la localizzazione delle risorse nella radice del persorso.\nUsa l'annidamento per indicare una raccolta di elementi. Per esempio,\nper il caso sopra, dove dyno dipende da app che dipende da org:\n\n```\n/orgs/{org_id}\n/orgs/{org_id}/apps\n/apps/{app_id}\n/apps/{app_id}/dynos\n/dynos/{dyno_id}\n```\n\n### Risposte\n\nLa sezione delle risposte fornisce una panoramica sui pattern da utilizzare per le risposte della API\n\n#### Ritorna sempre un codice di stato appropriato\n\nRitorna un codice di stato HTTP appropriato per ogni risposta.\nLe risposte con esito positivo, dovrebbero essere accompagnate da codici di stato come di seguito:\n\n* `200`: Richiesta completata con successo per una chiamata (sincrona) `GET`, `DELETE` o\n `PATCH`, oppure per una chiamata `PUT` (sincrona) che ha completato l'update di una risorsa\n* `201`: Richiesta completata con successo per una chiamata (sincrona) `POST`, o `PUT` che ha creato una nuova risorsa\n* `202`: Richiesta completata con successo per una chiamata `POST`, `PUT`, `DELETE`, o `PATCH` che viene processata in modo asincrono\n* `206`: Richiesta completata con successo per una chiamata `GET`, dove pero viene restituita una risposta parziale: vedi [Dividi risposte molto lunghe in piu richieste con range](SUMMARY.md#dividi-risposte-molto-lunghe-in-piu-richieste-con-range)\n\nFai molta attenzione all'utilizzo dei codici di errore per l'autenticazione e l'autorizzazione:\n\n* `401 Unauthorized`: Richiesta fallita per utente non autenticato\n* `403 Forbidden`: Richiesta fallita perchè l'utente non è autorizzato ad accedere ad una risorsa\n\nRitorna codici di errore adatti fornendo informazioni aggiuntive sul tipo di errore:\n\n* `422 Unprocessable Entity`: La tua richiesta è stata compresa, ma contiene dei parametri non validi.\n* `429 Too Many Requests`: Hai superato il limite di richieste, riprova più tardi\n* `500 Internal Server Error`: Qualcosa è andato storto, controlla lo stato del sito/servizio ed eventualmente segnala l'errore\n\nFai sempre riferimento alle specifiche [HTTP response code spec](https://tools.ietf.org/html/rfc7231#section-6)\nper i codici di stato e per gli errori\n\n#### Fornisci le risorse interamente, quando possibile\n\nFornisci la rappresentazione dell'intera risorsa (es. oggetto con tutti gli attributi)\nquando possible nella risposta. Fornisci sempre la risorsa completa con un codice 200 o 201, incluse nelle richieste \n`PUT`/`PATCH` e `DELETE`, es:\n\n```bash\n$ curl -X DELETE \\\n https://service.com/apps/1f9b/domains/0fd4\n\nHTTP/1.1 200 OK\nContent-Type: application/json;charset=utf-8\n...\n{\n \"created_at\": \"2012-01-01T12:00:00Z\",\n \"hostname\": \"subdomain.example.com\",\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"updated_at\": \"2012-01-01T12:00:00Z\"\n}\n```\n\nle risposte con codice 202 non includono l'intera rappresentazione della risorsa,\nes:\n\n```bash\n$ curl -X DELETE \\\n https://service.com/apps/1f9b/dynos/05bd\n\nHTTP/1.1 202 Accepted\nContent-Type: application/json;charset=utf-8\n...\n{}\n```\n\n#### Fornisci gli (UU)IDs delle risorse\n\nAssegna ad ogni risorssa un attributo `id` di default. Usa gli UUIDs a meno che tu\nnon abbia una buona ragione per non farlo. Non usare gli IDs perchè non sono globalmente \nunici, specialmente quando si hanno più instanze del servizio o delle risorse nel servizio, specialmente\ngli IDs auto-incrementali.\n\nVisualizza gli UUIDs in formato `8-4-4-4-12` minuscolo, es:\n\n```\n\"id\": \"01234567-89ab-cdef-0123-456789abcdef\"\n```\n\n#### Fornisci dei timestamps standard\n\nFornisci di default i timestamp `created_at` e `updated_at` per le risorse, es:\n\n```javascript\n{\n // ...\n \"created_at\": \"2012-01-01T12:00:00Z\",\n \"updated_at\": \"2012-01-01T13:00:00Z\",\n // ...\n}\n```\n\nQuesti timestamp possono non avere senso per alcune risorse, in questo caso possono \nessere omessi.\n\n#### Usa date in formato UTC formattate in ISO8601\n\nAccetta e ritorna le date solo in formato UTC. Visualizza le date nel formato\nISO8601, es:\n\n```\n\"finished_at\": \"2012-01-01T12:00:00Z\"\n```\n\n#### Annida relazioni tramite le chiavi esterne (foreign-key)\n\nSerializza i riferimenti delle chiavi esterne con un oggetto annidato, es:\n\n```javascript\n{\n \"name\": \"service-production\",\n \"owner\": {\n \"id\": \"5d8201b0...\"\n },\n // ...\n}\n```\n\nInvece di, es:\n\n```javascript\n{\n \"name\": \"service-production\",\n \"owner_id\": \"5d8201b0...\",\n // ...\n}\n```\n\nQuesto approccio rende possibile la visualizzazione di più informazioni sulla risorsa\nin questione senza dover cambiare la struttura della risposta o introdurre altri campi nella risposta stessa, es:\n\n```javascript\n{\n \"name\": \"service-production\",\n \"owner\": {\n \"id\": \"5d8201b0...\",\n \"name\": \"Alice\",\n \"email\": \"alice@heroku.com\"\n },\n // ...\n}\n```\n\n#### Genera errori strutturati\n\nGenera i corpi di risposta degli errori in modo consistente e strutturato.\nIncludi un riferimento `id` all'errore in modo che sia leggibile da una macchina, e un\ncampo `message` che sia comprensible all'utente e, opzionalmente un campo `url` che porta \nl'utente ad una descrizione più dettagliata dell'errore in questione e come risolverlo, es:\n\n```\nHTTP/1.1 429 Too Many Requests\n```\n\n```json\n{\n \"id\": \"rate_limit\",\n \"message\": \"Account reached its API rate limit.\",\n \"url\": \"https://docs.service.com/rate-limits\"\n}\n```\n\nDocumenta il formato dell'errore e il possibile error `id` che l'utente può incontrare.\n\n#### Visualizza lo stato del limite delle richieste\n\nMisura i limiti di richieste dai client per proteggere la stabilità del servizio e mantenere una\nqualita altà per gli altri clients. Puoi usare un \n[token bucket algorithm](http://en.wikipedia.org/wiki/Token_bucket) per misurare e monitorare il\nlimite delle richieste\n\nIn questo caso, ritorna il numero di richieste rimanenti in ogni richiesta nell'header\n`RateLimit-Remaining`.\n\n#### Mantieni il JSON minimizzato in tutte le risposte\n\nGli spazi bianchi extra aumentano inutilmente la dimensione delle richieste/risposte,\ninoltre molti clients adottano automaticamente processi di \"prettify\" sulle risposte JSON. Rimane una scelta\nmigliore mantenere le risposte JSON minimizzate, es:\n\n```json\n{\"beta\":false,\"email\":\"alice@heroku.com\",\"id\":\"01234567-89ab-cdef-0123-456789abcdef\",\"last_login\":\"2012-01-01T12:00:00Z\",\"created_at\":\"2012-01-01T12:00:00Z\",\"updated_at\":\"2012-01-01T12:00:00Z\"}\n```\n\nInvece di, es:\n\n```json\n{\n \"beta\": false,\n \"email\": \"alice@heroku.com\",\n \"id\": \"01234567-89ab-cdef-0123-456789abcdef\",\n \"last_login\": \"2012-01-01T12:00:00Z\",\n \"created_at\": \"2012-01-01T12:00:00Z\",\n \"updated_at\": \"2012-01-01T12:00:00Z\"\n}\n```\n\nPuoi considerare di fornire opzionalmente ai clients l'opportunità di recuperare delle risposte\npiù verbose (es. `?pretty=true`) o utilizzando un header `Accept` (es. `Accept: application/vnd.heroku+json; version=3; indent=4;`).\n\n### Artefatti\n\nLa sezione artefatti descrive gli oggetti che vengono utilizzati per gestire la progettazione delle API\n\n#### Fornisci uno schema JSON interpretabile\n\nFornisci uno schema JSON interpretabile per descrivere in maniera formale e precisa la tua API.\nPuoi usare [prmd](https://github.com/interagent/prmd) per gestire lo schema e assicurarti della sua \nvalidità usando il comando `prmd verify`.\n\n#### Fornisci una documentazione comprensibile allo sviluppatore\n\nFornisci una documentazione comprensibile che lo sviluppatore e i clients possono consultare per\nusare la tua API.\n\nSe crei uno schema utilizzando prmd come descritto sopra, potrai facilmente generare un documento in formato\nMarkdown per tutti gli endpoints usando il comando `prmd doc`.\n\nOltre alle specifiche degli endpoints, fornisci una panoramica della API con le seguenti \ninformazioni:\n\n* Autenticazione, specificando come ottenere ed usare un access token\n* Stabilità della API e versionamento, specificando come scegliere la versione della API\n* I comuni headeer delle richieste e delle risposte\n* Errori in formato serializzato\n* Esempi di utilizzo della tua API in diversi linguaggi\n\n#### Fornisci degli esempi\n\nFornisci dei semplici esempi eseguibili che gli utenti possano provare \nvelocemente tramite i loro terminali, per vedere il funzionamento delle chiamate alle API.\nPer essere più chiaro possibile, descrivi gli esempi in modo molto dettagliato, per diminuire\nin maniera considerevole il lavoro dell'utente che dovrà provare ed usare l'API, es:\n\n```bash\n$ export TOKEN=... # acquire from dashboard\n$ curl -is https://$TOKEN@service.com/users\n```\n\nSe usi [prmd](https://github.com/interagent/prmd) per generare la documentazione in formato Markdown,\notterrai automaticamente degli esempi per ogni endpoint.\n\n#### Specifica la stabilità della tua API\n\nSpecifica la stabilità della tua API oppure dei vari endpoints per quanto riguarda la maturità e la stabilità\ndella stessa, es. tramite dei flag prototype/development/production.\n\nDai un'occhiata a [Heroku API compatibility policy](https://devcenter.heroku.com/articles/api-compatibility-policy)\nper possibili cambiamenti nella stabilità o nella gestione delle policy.\n\nUna volta che la tua API è pronta per andare in produzione ed è stabile, non fare cambiamenti non retrocompatibili.\nSe hai bisogno di fare dei cambiamenti non retrocompatibili, crea una nuova API con un nuovo numero di versione.\n\n\n\n" } ]