SitePoint Sponsor

User Tag List

Results 1 to 8 of 8

Thread: API Responses

  1. #1
    SitePoint Guru phantom007's Avatar
    Join Date
    May 2008
    Posts
    752
    Mentioned
    3 Post(s)
    Tagged
    0 Thread(s)

    Question API Responses

    Hi

    I have spent the past few days doing some research on the API responses of various online services. I am confused and I want your suggestions.

    Do you think the following response makes sense and is industry standard way of generating an API response?


    Success XML
    Code:
    <?xml version='1.0' encoding='UTF-8'?>
    <output>
     <result>1</result>
     <message>User Added Successfully</message>
    </output>
    Success JSON
    Code:
    {"result":true,"message":"User Added Successfully"}


    Error XML
    Code:
    <?xml version='1.0' encoding='UTF-8'?>
    <output>
     <result>0</result>
     <message>User Already Exits</message>
    </output>
    Error JSON
    Code:
    {"result": false, "message":"User Already Exits"}
    In the above responses, I am sending a "result" key that holds a boolean value (true / false). True in case of success and false in case an error occurs.

    The second key is "message" that holds the respective messages.

    The reason I am asking this question is because one of my friend claims that its not a standard way of sending API responses and that we do not need to send the "result" key at all. We should return a key "errMsg" with the error message in case of error and in case of success we can send a true value. And users who are using the API can check if the "errMsg" key exists then handle the response as an error otherwise assume it as a success.

    So can someone throw some light on this please?

    Thanks in advance

  2. #2
    SitePoint Zealot
    Join Date
    Apr 2005
    Location
    London
    Posts
    163
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    As a consumer of services, I prefer the 'status' or 'result code' always present as part of the response payload... less code for me to write.

    Technically it doesn't matter as long as you agree / document your format.

    Why are you using 0/1 for xml, but booleans for JSON? keep it consistent.

  3. #3
    SitePoint Guru phantom007's Avatar
    Join Date
    May 2008
    Posts
    752
    Mentioned
    3 Post(s)
    Tagged
    0 Thread(s)
    For XML I am actually passing booleans, but it gets converted to 0 / 1. Not sure why

  4. #4
    SitePoint Author silver trophybronze trophy
    wwb_99's Avatar
    Join Date
    May 2003
    Location
    Washington, DC
    Posts
    10,653
    Mentioned
    4 Post(s)
    Tagged
    0 Thread(s)
    I don't think there is a standard, but lots of people need to pass back a success flag and a message. From a consumer's standpoint being able to check a boolean value is probably slightly more convenient than checking the message. Furthermore, you might want to transfer some information with success so presence of a message isn't necessarily an indication of failure.

  5. #5
    SitePoint Member
    Join Date
    May 2013
    Location
    Richmond VA
    Posts
    12
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Industry standard or not being able to treat the response in a uniform way makes the life of the consumer easier. When crafting API responses I often include a status key and which usually matches up with the HTTP status of the response. For instance if there is a validation error I will return a HTTP status of 409 and in the response include the status like {status: 409, errors: []}. If the request was a success something like {status: 200, message: ""}.

  6. #6
    SitePoint Author silver trophybronze trophy
    wwb_99's Avatar
    Join Date
    May 2003
    Location
    Washington, DC
    Posts
    10,653
    Mentioned
    4 Post(s)
    Tagged
    0 Thread(s)
    If you are going to do that why not just pass the responses as HTTP status codes? That *is* an industry standard.

  7. #7
    SitePoint Member
    Join Date
    May 2013
    Location
    Richmond VA
    Posts
    12
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Please re-read my post. The answer to your question is in there.

  8. #8
    SitePoint Author silver trophybronze trophy
    wwb_99's Avatar
    Join Date
    May 2003
    Location
    Washington, DC
    Posts
    10,653
    Mentioned
    4 Post(s)
    Tagged
    0 Thread(s)
    Yup, somehow read past that one.

    I've used the http status code as error type indicator here and there, haven't really fallen in or out of love with it. This was mainly for SOAPy stuff where one couldn't send status messages effectively though.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •