Being nice to other developers with REST services

REST services are really nice, really fast and easy to create, but sometimes we forget in our haste to get them out the door that a little bit of structure will help both our selves and any third party developer than might user them, eg, if when a call is made to your service

[]

is returned, what does that mean? was it sucessfull but there is no data, or was there an error in your call, a bit of context would go a long way, the easiest way round this is a little wrapper class, nothing fancy, just enough to throw the front end devs a bone, my basic one looks like this

package com.ldc.classes;
public class RESTReturn {  
    public static final Integer SUCCESS = 0;
    public static final Integer FAILED_GENERAL = 1;
    public static final Integer FAILED_INVALID_PARAMETER_VALUES = 2;
    public static final Integer FAILED_MISSING_PARAMETER = 3;
    public static final Integer FAILED_AUTHENTICATION_FAILURE = 4;
    public static final Integer FAILED_AUTHORISATION_FAILURE = 5;
    public static final Integer FAILED_AUTHENTICATION_EXPIRED = 6;
    public RESTReturn() {
    }
    public RESTReturn(int returnStatusParm) {
        returnStatus = returnStatusParm;
        returnStatusDesc = statusToString(returnStatusParm);
    }
    private int returnStatus;
    private String returnStatusDesc;
    private Object payload;
    public int getReturnStatus() {
        return returnStatus;
    }
    public void setReturnStatus(int returnStatus) {
        this.returnStatus = returnStatus;
    }
    public String getReturnStatusDesc() {
        return returnStatusDesc;
    }
    public void setReturnStatusDesc(String returnStatusDesc) {
        this.returnStatusDesc = returnStatusDesc;
    }
    public Object getPayload() {
        return payload;
    }
    public void setPayload(Object payload) {
        this.payload = payload;
    }
    public static String statusToString(Integer wsReturn) {
        if (SUCCESS.equals(wsReturn)) {
            return "It Worked";
        } else if (FAILED_GENERAL.equals(wsReturn)) {
            return "Error: This call caused an error";
        } else if (FAILED_INVALID_PARAMETER_VALUES.equals(wsReturn)) {
            return "Error: Something you gave me was rubbished";
        } else if (FAILED_MISSING_PARAMETER.equals(wsReturn)) {
            return "Error: You left somthing out";
        } else if (FAILED_AUTHENTICATION_FAILURE.equals(wsReturn)) {
            return "Error: Err user name or password was wrong";
        } else if (FAILED_AUTHORISATION_FAILURE.equals(wsReturn)) {
            return "Error: You you can log on, but you dont have rights to do that";
        } else if (FAILED_AUTHENTICATION_EXPIRED.equals(wsReturn)) {
            return "Error: Your logon has expired, sorry";
        } else {
            return null;
        }
    }
}

and I would use it a bit like this

package com.ldc.classes;
import java.util.List;
public class Getaddress {
    public RESTReturn getAddressInJSON() {
        int callStatus = RESTReturn.SUCCESS;
        List<Address> someAddresses = null;
        try {
            someAddresses = doSomthingToGetALoadOfAddress();
        } catch (Exception e) {
            callStatus = RESTReturn.FAILED_GENERAL;
        }
        RESTReturn restReturn = new RESTReturn();
        restReturn.setReturnStatus(callStatus);
        restReturn.setReturnStatusDesc(RESTReturn.statusToString(callStatus));
        restReturn.setPayload(someAddresses);
        return restReturn;
    }
}

so instead of

[]

I would get

{"returnStatus":1,"returnStatusDesc":"Error: This call caused an error", "payload" : "[]"}

which at least tells you that something is not right with the world

Obviously you can get as creative as you want, and a lot depends on how good your internal functions are at displaying their unhappiness, but every little helps and you will make better friends with your client side devs for a bit of consideration like this

Thanks to Ben Poole for pointing out to me that I’m behind the times as normal and this is standard practice, doh!!

Old Comments
————
##### Mark Barton(01/06/2012 14:32:21 GDT)
I wonder though if you should throw a HTTP Status != 200 e.g. 404 along with the custom exception error message.

Its then trivial to catch an error using something like JQuery.
##### Mark(01/06/2012 14:37:24 GDT)
Good point, in this case I have found that this kind of structure is most beloved of the mobile apps lot, who prefer to handle such errors separately due to the someone unreliable nature of mobile networks, but it would be a good idea to use http status items (goes off to look)

Leave a Reply Cancel reply