How to properly design a data exchange protocol between a client and a web service?

Question

Programming

Hey!

I am creating some web service with a public API available over HTTP. Since the API is supposed to be public, I want to take into account all the pitfalls in advance - otherwise you will have to make a new version of the protocol and support both - horror :)

Communication between the client and the server works in the best traditions of HTTP: request-response. All request parameters are passed in accordance with HTTP rules - via the address bar for GET requests and via multipart/form-data for POST. For different tasks, different URLs, for example, a login request is sent to http://example.com/login , and a registration request is sent to http://example.com/register )

However, it is not very clear how to arrange the transfer of data back to the client. At the moment, I encode information about the result of the request with the HTTP status ( 200, 403, 404, 500, etc.), and if something else is needed, then I simply pass the values ​​​​in solid text to the client in the given order, separated by a delimiter character (for example, 17:150:колбаса) in response body.

I thought it made sense to use XML for this, because now everyone does it - probably for a reason. But, having studied this topic, I realized that with this approach, it is also accepted to transfer query parameters to the server in the form of XML.

How to be? Use a simple delimited parameter string or switch to XML? Is it still possible to send data to the server in the form of query parameters?

Interested in answers in terms of what is accepted or not accepted and how bad it is to deviate from the accepted. Physically, anything can be done.

Answer 1

First, forget about XML, bureaucrats invented it. So let them use it in their banks and tax authorities. To parse and encode JSON, a couple of functions of 10 lines each are enough. To parse XML, even if it contains a couple of values, you need to load monstrous libraries.
Secondly, since you are making a web application, use the capabilities of the HTTP protocol. This means REST ideology, not RPC. That is, instead of some “procedures” or “functions”, you dance from objects and standard actions.
For example, you have an object with id obj_id. For any access to it, a URL like
example.com/path/to/obj_id
is used. Further, 4 actions are possible on this URL (http verb):
GET example.com/path/to/obj_id — get object data
PUT example.com/path/to/obj_id - change the object
DELETE example.com/path/to/obj_id - delete the object
POST example.com/path/to/ - create a new object in the /path/to folder
GET example.com/ path/to/ — get all objects in the /path/to folder
Depending on the result of the operation, you should return the correct error codes (200 OK, 404 Not Found, 403 Forbidden, etc.).
Parameters of more complex requests are used as get-parameters, for example
GET example.com/path/to/?search=blabla
- search for objects
Or you can transfer some of the parameters to the URL:
GET example.com/my/report/01.01.2011-31.12 .2011/

Answer 2

add the format parameter to the request and, depending on its value, return json/xml/csv…

Answer 3

XML is slower though.
I chose JSON in a similar situation because of its speed.
You need to evaluate whether you can use JSON everywhere.
If not, then there are no other options besides XML.

Answer 4

I myself faced such a task - it is not so simple. I agree with most of the advice above.
1) Use json-encode - a very common and proven solution. Much easier than xml.
2) Separation of request types into HTTP methods GET, POST, PUT, DELETE is better not to do, although this is correct. Limit yourself to GET and POST. This is due to the fact that many clients will not be able to use the same DELETE - well, at least flash.
3) Consider your API versions right away. That is, the request must have a type parameter v=1. This will be very useful to you in the future.

Answer 5

I would suggest not to reinvent the wheel, but to use RPC / SOAP

Answer 6

Often the choice of format is made either through a "file extension" ( domain.com/method.xmlvs method.json) or through an HTTP header Accept.

Answer 7

Based on my experience, the procedure should be:
1. Try different APIs as a "user" (facebook, twitter, vkontakte, soundcloud, youtube);
2. Understand what you like and what you don't (again, as a "user");
3. Make your API based on the first two points.
In my opinion, it is necessary to adhere to the REST ideology (with the ability to do without it), and allow both xml and json formats.

Answer 8

I thought it made sense to use XML for this, because now everyone does it - probably for a reason. But, having studied this topic, I realized that with this approach, it is also accepted to transfer query parameters to the server in the form of XML.

I don't quite understand how you imagine a GET request to a server with XML data.
The response from the server in the form of XML is a common practice. Used in payment systems everywhere.