I have a web service (axis2) and the server performs 4 primary operations: createX, removeX, getX and updateX
Where X is represented by a combination of 4 values: id1, id2, id3 and id4
So, to simplify developer life, we created 3 extra helper functions:
removeXForId, getXForId and updateXForId where we represent the set of 4 values as 1 Identifier so that the developers who are calling us do not need to pass all those 4 values again and again and just store the unique identifier on their end.
But, we cannot also completely remove removeX, getX and updateX operations completely abd just rely on the unique identifier as some use cases need to pass all 4 set of values.
So, now we have around 7 operations where half (3) of them are duplicate operations with different input values.
Operations:
/createX
/getX {input: id1, id2, id3, id4}
/getXForId {input: id1234}
/removeX
/removeXForId
/updateX
/updateXForId
Is this a good practice?
UPDATE:
getX is exactly the same as getXForId in terms of behavior except the input arguments.
getX takes in 4 inputs: val1, val2, val3 and val4. But getXForId takes in just 1 ID which represents (val1, val2, val3 and val4)
val1, val2, val3 and val4 are some how related to each other, they in combination represent a unique link to a product in our system. So we tried to club them together.
Best Answer
It would make more sense to me to organize the API around resources and use the verbs (GET, PUT, POST, DELETE) that come with the http protocol, in short: Make it more RESTful, that is surely considered good practice.
This is a good succinct talk on API design that also analyzes popular APIs such as facebook's or twitter's.
I am lost on the difference between your/getX
and/getXForId
so I can't really give you an example of how I would change your API.Edit
I tried to model the API in Sinatra. It is pretty self explanatory and straight forward. (I saw you are using axis but it's been a while since I did serious Java). If you are serious about RESTful then you probably want to drop the approach with the four ids. However the approach works:
Testing the API with curl:
The script returns the following:
What you can see is that nesting resources and the four parameter approach does not work well together. Maybe one could model it differently and do something like
/X/:id1/:id2/:id3/:id4
.