nodejs/nodebestpractices
1
0
Fork 0
mirror of https://github.com/goldbergyoni/nodebestpractices.git synced 2025-10-29 08:37:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #790 from VinayaSathyanarayana/patch-4

Browse Source 
Refer to OpenAPI
This commit is contained in:
Kevyn Bruyere
2020-11-23 18:31:52 +01:00
committed by GitHub
parent 37e7bfa76a d60009a9a3
commit cf9685ca7b
1 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
sections/errorhandling/documentingusingswagger.md
View File

@ -1,8 +1,8 @@
# Document API errors using Swagger or GraphQL
# Document API errors using OpenAPI Specification (earlier known as Swagger) or GraphQL
### One Paragraph Explainer
REST APIs return results using HTTP status codes, it’s absolutely required for the API user to be aware not only about the API schema but also about potential errors – the caller may then catch an error and tactfully handle it. For example, your API documentation might state in advance that HTTP status 409 is returned when the customer name already exists (assuming the API register new users) so the caller can correspondingly render the best UX for the given situation. Swagger is a standard that defines the schema of API documentation offering an eco-system of tools that allow creating documentation easily online, see print screens below
REST APIs return results using HTTP status codes, it’s absolutely required for the API user to be aware not only about the API schema but also about potential errors – the caller may then catch an error and tactfully handle it. For example, your API documentation might state in advance that HTTP status 409 is returned when the customer name already exists (assuming the API register new users) so the caller can correspondingly render the best UX for the given situation. OpenAPI (eka Swagger) is a standard that defines the schema of API documentation offering an eco-system of tools that allow creating documentation easily online, see print screens below
If you have already adopted GraphQL for your API endpoints, your schema already contains strict guarantees as to what errors should look like ([outlined in the spec](https://facebook.github.io/graphql/June2018/#sec-Errors)) and how they should be handled by your client-side tooling. In addition, you can also supplement them with comment-based documentation.