# API Design Guide This is the home of the API Design Guide published by Stafrænt Ísland as a best practice guide for API development. It should help synchronize the work between developers and make working together easier. The guide covers the relevant design principles and patterns to use so the consumer experience is enjoyable and consistent throughout APIs. This guide is under constant review and updates will be made over time as new design patterns and styles are adopted. All feedback is welcomed and encouraged to help make the guide better so please feel free to create pull requests. ## Content * [Once-Only](https://docs.devland.is/technical-overview/api-design-guide/once-only) * [Resource Oriented Design](https://docs.devland.is/technical-overview/api-design-guide/resource-oriented-design) * [Design flow](https://docs.devland.is/technical-overview/resource-oriented-design#design-flow) * [Resource](https://docs.devland.is/technical-overview/resource-oriented-design#resources) * [Naming Conventions](https://docs.devland.is/technical-overview/api-design-guide/naming-conventions) * [General](https://docs.devland.is/technical-overview/naming-conventions#general) * [Resources](https://docs.devland.is/technical-overview/naming-conventions#resources) * [Fields](https://docs.devland.is/technical-overview/naming-conventions#fields) * [GraphQL Naming Conventions](https://docs.devland.is/technical-overview/api-design-guide/graphql-naming-conventions) * [Case styles](https://docs.devland.is/technical-overview/graphql-naming-conventions#case-styles) * [Input objects naming conventions](https://docs.devland.is/technical-overview/graphql-naming-conventions#input-objects-naming-conventions) * [Query naming conventions](https://docs.devland.is/technical-overview/graphql-naming-conventions#query-naming-conventions) * [Mutation naming conventions](https://docs.devland.is/technical-overview/graphql-naming-conventions#mutation-naming-conventions) * [Integrating naming conventions into shared api](https://docs.devland.is/technical-overview/graphql-naming-conventions#integrating-naming-conventions-into-shared-api) * [Data Definitions](https://docs.devland.is/technical-overview/api-design-guide/data-definitions) * [Text encoding](https://docs.devland.is/technical-overview/data-definitions#text-encoding) * [JSON](https://docs.devland.is/technical-overview/data-definitions#json) * [National identifier](https://docs.devland.is/technical-overview/data-definitions#national-identifier) * [Language and currency](https://docs.devland.is/technical-overview/data-definitions#language-and-currency) * [Date and time](https://docs.devland.is/technical-overview/data-definitions#date-and-time) * [Timestamp data](https://docs.devland.is/technical-overview/data-definitions#timestamp-data) * [Data transfer objects](https://docs.devland.is/technical-overview/api-design-guide/data-transfer-objects) * [Pagination](https://docs.devland.is/technical-overview/api-design-guide/pagination) * [PageInfo](https://docs.devland.is/technical-overview/pagination#pageinfo) * [Pagination Query parameters](https://docs.devland.is/technical-overview/pagination#pagination-query-parameters) * [Monorepo library](https://docs.devland.is/technical-overview/pagination#monorepo-library) * [Methods](https://docs.devland.is/technical-overview/api-design-guide/methods) * [Methods mapping to HTTP verbs](https://docs.devland.is/technical-overview/methods#methods-mapping-to-http-verbs) * [Custom methods (RPC)](https://docs.devland.is/technical-overview/methods#custom-methods-rpc) * [REST Request](https://docs.devland.is/technical-overview/api-design-guide/rest-request) * [Query parameters](https://docs.devland.is/technical-overview/rest-request#query-parameters) * [Path parameters](https://docs.devland.is/technical-overview/rest-request#path-parameters) * [REST Response](https://docs.devland.is/technical-overview/api-design-guide/rest-response) * [General](https://docs.devland.is/technical-overview/rest-response#general) * [GET](https://docs.devland.is/technical-overview/rest-response#get) * [POST](https://docs.devland.is/technical-overview/rest-response#post) * [PUT](https://docs.devland.is/technical-overview/rest-response#put) * [PATCH](https://docs.devland.is/technical-overview/rest-response#patch) * [DELETE](https://docs.devland.is/technical-overview/rest-response#delete) * [Errors](https://docs.devland.is/technical-overview/api-design-guide/errors) * [Response Body](https://docs.devland.is/technical-overview/errors#response-body) * [Documentation](https://docs.devland.is/technical-overview/api-design-guide/documentation) * [Describe error handling](https://docs.devland.is/technical-overview/documentation#describe-error-handling) * [Provide feedback mechanism](https://docs.devland.is/technical-overview/documentation#provide-feedback-mechanism) * [Example](https://docs.devland.is/technical-overview/documentation#example) * [Setup example](https://docs.devland.is/technical-overview/documentation#setup-example) * [Versioning](https://docs.devland.is/technical-overview/api-design-guide/versioning) * [Version changes](https://docs.devland.is/technical-overview/versioning#version-changes) * [URLs](https://docs.devland.is/technical-overview/versioning#urls) * [Increment version numbers](https://docs.devland.is/technical-overview/versioning#increment-version-numbers) * [Deprecating API versions](https://docs.devland.is/technical-overview/versioning#deprecating-api-versions) * [Security](https://docs.devland.is/technical-overview/api-design-guide/security) * [Environments](https://docs.devland.is/technical-overview/api-design-guide/environments) * [Development](https://docs.devland.is/technical-overview/environments#development-environment) * [Test](https://docs.devland.is/technical-overview/environments#test-environment-for-providers-of-an-api) * [Sandbox](https://docs.devland.is/technical-overview/environments#sandbox-environment-for-consumers-of-an-api) * [Production](https://docs.devland.is/technical-overview/environments#production-environment) * [Example Service](https://docs.devland.is/technical-overview/api-design-guide/example) ## Changelog *Draft 4 - Published 2023-06-07* * Updated usage of [HTTP status codes](https://docs.devland.is/technical-overview/rest-response#http-status-codes) to use `204` instead of `404` when resources are not found or not accessible to the user. * Update [REST Requests](https://docs.devland.is/technical-overview/rest-request#working-with-sensitive-data) to describe arrays in query parameters and how to handle sensitive data in query and path parameters. * Update [Custom Methods (RPC)](https://docs.devland.is/technical-overview/methods#custom-methods-rpc) to use verbs instead of nouns for method names with `POST`. *Draft 3 - Published 2022-08-16* * Improving [Documentation](https://docs.devland.is/technical-overview/api-design-guide/documentation). * Adding description of Content Types in [REST Response](https://docs.devland.is/technical-overview/api-design-guide/rest-response). * Making `hasPreviousPage` and `startCursor` optional in [Pagination](https://docs.devland.is/technical-overview/api-design-guide/pagination). * Adding OWASP and IAS reference in [Security](https://docs.devland.is/technical-overview/api-design-guide/security). * Other small fixes. *Draft 2 - Published 2021-10-19* * Changing pagination description *Draft 1 - Published 2020-08-31* * Initial relase --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.devland.is/technical-overview/api-design-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.