www.webdeveloper.com
Results 1 to 4 of 4

Thread: API Responses

Hybrid View

  1. #1
    Join Date
    Sep 2006
    Posts
    655

    Lightbulb API Responses

    Hi

    This question is not specifically about PHP but since my application is in PHP I m posting it here.


    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
    Join Date
    Apr 2013
    Posts
    56
    I would suggest looking at some outputs of common public API's. For example Ebay, Amazon, Paypal and such should provide enough info on how the standard output should look like. It would be wise to ask yourself, what do I gain/loose with having result key-value pair? Does it offer better user/developer experience when using your API or does it not? In my opinion, enumeration value like your result makes sense for indicating output status.

  3. #3
    Join Date
    Aug 2004
    Location
    Ankh-Morpork
    Posts
    19,247
    I personally doubt there's much of a "standard" in this regard: for something that simple, I think any developer half-ways deserving of the name can understand your posted system and figure out how to work with it -- which seems good enough to me, regardless of whether it's the absolute "best" way or not.

    FWIW, the "standard" on the project I'm on here at work is similar: most JSON responses have a 'result_code' and 'result_msg' field at the top level, and then additional parameters as applicable, often in arrays, sometimes 2 or 3 levels deep. Fake example:
    Code:
    {
      "result_code": "S",
      "result_msg": "SUCCESS",
      "summary": {
        "foo": "something",
        "bar": "another thing"
      },
      "details": [
        {
          "providerNumber": "97432437",
          "productId": "ALL1",
          "sequenceNumber": "23",
          "timestamp": "2013-03-26T10:10:25.000000",
          "comment": "This is only a test."
        },
        {
          "providerNumber": "97432439",
          "productId": "ALL2",
          "sequenceNumber": "20",
          "timestamp": "2013-03-26T10:10:26.000000",
          "comment": "This is only another test."
        }
      ]
    }
    "Please give us a simple answer, so that we don't have to think, because if we think, we might find answers that don't fit the way we want the world to be."
    ~ Terry Pratchett in Nation

    eBookworm.us

  4. #4
    Join Date
    Dec 2012
    Posts
    97
    As far as I've gathered from my short experience of working with APIs, you pretty much set your own standard. As long as you keep everything consistent and do return some form of success/error response it's entirely up to you.

Thread Information

Users Browsing this Thread

There are currently 1 users browsing this thread. (0 members and 1 guests)

Posting Permissions

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



Recent Articles