11

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.

Harshit
  • 711
  • 1
  • 9
  • 29

2 Answers2

13

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.

Zdenek
  • 3,653
  • 27
  • 34
3

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.

Kyle Clegg
  • 38,547
  • 26
  • 130
  • 141
  • Ya this could be a solution. Actually I was looking for something where the error section would be highlighted for all the possible error codes. Any other API documentation tool you know about. Thanks for the answer. – Harshit May 29 '14 at 19:02
  • Mashery is another one. We evaluated them and Apiary and went with Apiary and have no complaints. Been great so far. – Kyle Clegg May 29 '14 at 21:47