Menu
I want to specify the various exceptions/errors that have to be returned while making an API call. How do I achieve this with Apiary.
208
Limitations: The console calls to the API aren’t direct. The data from the browser are sent to the Apiary infrastructure, the HTTP request is made from Apiary servers without the CORS limitation and the API response is sent back from Apiary servers to the browser to be shown to the user. Requirements: The API has to be accessible from the internet.
Many people have different designs for specifying the errors in the API response - some just return status code without any response message, while some describe a simple text message in the body and others specify custom JSON schema for specifying the errors.
Using the Editor # The Apiary Editor shows a preview of your documentation while providing instant feedback to ensure correct syntax in your API document. Your API document will be parsed with warnings and errors as you type. These errors will be displayed both in the editor header and on the lines where the warnings and errors exist.
The Blueprint starts with a metadata section. The FORMAT keyword is required and denotes that document is API Blueprint. You can also add HOST, which should have value of your production API URI. This will allow you to test and debug production calls from Apiary.
Kyle's response is indeed correct. I will just add that if you want to add little bit more semantics to this you can write the other possible responses like this:
## POST /users/resendVerification/{userId}
Resends the user's verification code to the email address on record.
+ Response 201
+ Response 403
Returned if the user does not have access to the requested account
+ Body
+ Response 404
Returned if a user was not found for the given userId
+ Body
Note: The + Body is needed (even though it is empty) to distinguish the description from a message-body.
193
I'm not aware of a specific syntax for error codes. In the past I've simply used bullet points. For example, this is my code for a re-request verification code API.
## POST /users/resendVerification/{userId}
Resends the user's verification code to the email address on record.</br>
• 403 is returned if the user does not have access to the requested account</br>
• 404 is returned if a user was not found for the given userId</br>
+ Response 201
Hope that helps.
24
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
