From 3f619fc6b0ecd81027a4ccaf6455ceae14c5cc35 Mon Sep 17 00:00:00 2001 From: Vinaya Sathyanarayana Date: Wed, 4 Nov 2020 22:16:33 +0530 Subject: [PATCH 1/3] Refer to OpenAPI Refer to OpenAPI --- sections/errorhandling/documentingusingswagger.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sections/errorhandling/documentingusingswagger.md b/sections/errorhandling/documentingusingswagger.md index 3341b0c1..92a5947c 100644 --- a/sections/errorhandling/documentingusingswagger.md +++ b/sections/errorhandling/documentingusingswagger.md @@ -1,8 +1,8 @@ -# Document API errors using Swagger or GraphQL +# Document API errors using OpenAPI Specification (eka 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. From ae703cb957273864061737d457e4673de7458bf4 Mon Sep 17 00:00:00 2001 From: Vinaya Sathyanarayana Date: Mon, 23 Nov 2020 13:51:43 +0530 Subject: [PATCH 2/3] Update documentingusingswagger.md Updated EKA --- sections/errorhandling/documentingusingswagger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/errorhandling/documentingusingswagger.md b/sections/errorhandling/documentingusingswagger.md index 92a5947c..a35a7caf 100644 --- a/sections/errorhandling/documentingusingswagger.md +++ b/sections/errorhandling/documentingusingswagger.md @@ -1,4 +1,4 @@ -# Document API errors using OpenAPI Specification (eka Swagger) or GraphQL +# Document API errors using OpenAPI Specification (earliar known as Swagger) or GraphQL ### One Paragraph Explainer From d60009a9a33626e4c5c08917414f338184c0ab2c Mon Sep 17 00:00:00 2001 From: Vinaya Sathyanarayana Date: Mon, 23 Nov 2020 21:20:19 +0530 Subject: [PATCH 3/3] Update documentingusingswagger.md Spelling Corrected --- sections/errorhandling/documentingusingswagger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/errorhandling/documentingusingswagger.md b/sections/errorhandling/documentingusingswagger.md index a35a7caf..b91e7d05 100644 --- a/sections/errorhandling/documentingusingswagger.md +++ b/sections/errorhandling/documentingusingswagger.md @@ -1,4 +1,4 @@ -# Document API errors using OpenAPI Specification (earliar known as Swagger) or GraphQL +# Document API errors using OpenAPI Specification (earlier known as Swagger) or GraphQL ### One Paragraph Explainer