November 18, 2009 at 20:37

Tao of WebService. (Or let it be enough to reinvent the wheel!)

    imageRecently, an article was published on Habré under a provocative headline and a call for stopping the invention of bicycles in the API structure. Since the topic is interesting to me, I simply could not pass by.
    Alas, the reality behind the Habrakat greatly disappointed me - I saw another bike, and even with square wheels. (Colleagues, nothing personal, just a technical discussion.) True, the authors honestly said that they saw the fashionable word REST on several sites and decided to do it. Only now they understood this "REST" in their own way, approximately how Grandfather Schukar read and understood the explanatory dictionary.
    In this topic, I urge you to truly end bikes in the site APIs. After all, it turns out what a joke: IPA is being developed to simplify access to the site and ease of connecting external systems, but it turns out that it is even more difficult with it than without it :)

    A little lower under the cut, I will sign the death sentence for all bicycles in universal APIs. In order not to be unfounded, I will illustrate everything with examples.
    But I must warn you right away - after reading the article, you cannot look at the next Vasya Pupkin’s bicycle under the proud name “universal site API” without a gag reflex.

    The following questions will be considered in the narrative:
    1. Core technologies: XML-RPC, REST, SOAP and a brief comparison
    2. Tao of web service
    3. Enlightened APIs
    4. How to distinguish a site API from shit
    5. conclusions



    So today the most common ways to access site APIs are:
    1. XML-RPC.
    2. REST (with the proviso that this is not a protocol, but an approach).
    3. SOAP.


    Basic Technology and Comparison



    XML-RPC

    I think I’m not very mistaken if I say that XML-RPC is the progenitor of all this nonsense, which we now call the big words "web services" and "site api". It was developed in 1998 by order of Microsoft. At its core, it is the reincarnation of the good old RPC using message formatting in XML. The undoubted advantage of the protocol is its simplicity, and as a result, ease of implementation.
    Here is an example of a typical XML-RPC request:
    examples.getAirportCode567

    What you can get the same simple answer: 
    SVO


    Error messages look pretty much the same. Such an answer is easy to parse even for a person, not to mention the car. Such simplicity served him in two ways: on the one hand, it was not accepted by the customer and did not become a standard, and on the other, it was liked by a crowd of simple, undefiled programmers. These guys needed a simple and reliable means of exchanging information between systems, they did not want to bother with such crap as a beautiful URL, a document scheme and other academies. The first thing they wanted was a simple working system. And so far, XML-RPC has been helping them.
    So:
    +: simplicity, brevity of messages, minimal verification of the data format,
    -: insufficient rigor, a separate description of the service is required.

    REST

    Roy Fielding was probably the first to say “stop inventing bicycles” and “everything has already been stolen to us” in relation to web services. And maybe not the first one, in any case, his words sounded most loudly. In his dissertation, Architectural Styles and the Design of Network-based Software Architectures, he described the basic principles of REST (Representational State Transfer) - a web services architecture that changed developers' views by 180 degrees **. He said that “one should not dance from the corner, but from the stove” - in other words - one should not call the procedure and transfer the object to it, but refer to the object. No need to wind the bike on a moped. After all, the HTTP protocol itself already has a number of methods for working with objects: GET (receive), POST (send / create), PUT (update), DELETE (delete).
    Why tautology and call
    POST /api/object.php?object_id=445&action=delete&user_id=255&auth_key=0Jf4tet5 HTTP / 1.1

    When you can simply:
    DELETE / objects / 445 HTTP / 1.1

    Or the option is still practiced when POST is made to the resource itself, and delete is passed separately by the parameter:
    POST / objects / 445 HTTP / 1.1

    At the same time, if the XML-RPC uses only the transport part from the HTTP protocol to transmit the request / response XML, then REST uses HTTP in full: here there are authorization headers, content-negotiation - preferences in format, language, encoding and type response, various service headers, hemorrhage-free transmission of binary data, etc. Errors are well described by HTTP codes 4xx and 5xx. You can see that REST is an organic add-on over HTTP. This is not surprising because Roy is one of the developers of the HTTP protocol. In general, the more I understand this protocol, the more it seems to me that it is 20 years ahead of its time, and the further the web develops, the more opportunities we use from it.
    The message body itself can be transmitted in different formats: classic XML or geek JSON. In general, REST is not a protocol, it is an approach, and just here its flexibility is concluded, it kind of tells us: “Guys, take the basic principles, and then do as you like.” Proximity to the HTTP protocol simplifies and speeds up its processing by web servers.
    So:
    +: flexibility, simplicity, processing speed (especially important for large sites), organic protocol, multi-format, compactness.
    -: lack of strict data control; for practical reasons, you have to go beyond the ideal model.

    SOAP

    So we got to him - a protocol-gift! But it was on it that I realized the Tao of all web services and website api. I think everyone knows what the abbreviation SOAP stands for - Simple Object Access Protocol. This is how Microsoft should look like the perfect protocol for web services. Let's look at what a typical query looks like:
    Copy Source | Copy HTML
    2.     xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    3.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    4.     xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
                              schemas.xmlsoap.org/soap/envelope">
    5.   
    6.     
    7.       classifieds
    8.     
    9.   


    and the answer is:
    Copy Source | Copy HTML
    2.     xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    3.     xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
                              schemas.xmlsoap.org/soap/envelope">
    6.   
    7.     
    8.       schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
    9.     
    10.     
    11.       localhost:8080/axis2/services/MyService
    12.     
    13.     ECE5B3F187F29D28BC11433905662036
    14.   
    15.   
    16.     
    17.       classifieds
    18.     
    19.   


    - Fak may brain! - You will exclaim and you will be absolutely right. - Well, for the sake of transmitting a 10 byte wick, do I need to write all this crap?
    “Yes, ” Logic will say, and you will roll up your sleeves to learn all this bunch of technologies.

    - For some reason, XML Schema was also dragged here? What the hell? Are you sure that these guys correctly understand the meaning of the word “Simple”? - Such thoughts will visit you, and it’s good - you are on the right track.

    But that's not all: the more you dig into SOAP, the more all kinds of different technologies get on you. When you get to WSDL (Web Services Description Language), you will understand why, starting with some version, the developers no longer take the name SOAP as an abbreviation, and begin to understand literally - soap (“soap”). At this point, your thoughts will be occupied by one idea: why there is no rope technology in the whole technology zoo.

    After some time, you exclaim: “Well, nafig, let’s do it without me: you’ve come up with it yourself and you’re messing around. I’m not a megabyte of iksamel’s machine in your brain! ”
    Congratulations: now you have comprehended the dao of web services!

    Yes! The Tao of the web service is precisely this: it is the language of communication between machines and a person doesn’t need to get into it. You just need to use it. After all, when you need some kind of program, you run it, and do not get into the binary code to execute it in the brain. In the same way, you do not send HTTP requests by hand at the command line, but use a browser. So why bother climbing into this gopa with your bare hands, and boast about who climbed up to the elbow and who climbed to the shoulder? You just need to use it.


    Enlightened APIs


    The site’s API and web services are not something mercifully launched from us by the creators of the site! This is a banal library of functions that we can embed in our program. This conclusion becomes completely natural when you begin to think globally outside of your computer.
    If you need a new ready-made project, what do you do? Most likely just downloading, installing and using? Write at the beginning of the program use / require / import / include / ... and then just call the functions. Why should working with a web library be more difficult?
    Now, having become enlightened, we can start working with the enlightened API.

    Now, as an example, we will do work with the Aeroflot API for 1 minute, we will spy on the Sheremetyevo scoreboard without taking our ass off the chair. I take my favorite language and write all the examples in it. I am sure your language has similar modules. Well, if they are not there, then it's time to think about it, it is mutual love your ;-)

    Here there Aeroflot detail paints his miraculous API. At first glance, the description is rather miserable - a pure enumeration of methods and parameters. But how to call it, how to parse, what to do? And this is not our concern anymore - let the headache of the car about it - it’s iron, but I don’t want to load mine with bullshit. Therefore, my task is to find a machine-readable description of the service - the same WSDL and feed it to the computer.

    Copy Source | Copy HTML
    2. from ZSI.ServiceProxy import ServiceProxy #  импортируем замечательную либу Zolera Soap Infrastructure
    3. api = ServiceProxy('http://webservices.aeroflot.ru/flightstatus.asmx?WSDL')
    4. # ... и все! API сайта полностью готово к работе.
    5. # наш объект api содержит методы 
    6. AirportInfo()         Departure() 
    7. AirportList()         FlightInfo()
    8. Arrival()               FlightSearch()
    9.  
    10. # то есть все те, что описаны в доке. 
    11. # Нам осталось лишь вызвать их с нужными параметрами:
    12. airport_list = api.AirportList()
    13. airport_list
    14. {'AirportListResult': {'Airport': [{'city': 'Colombo',
    15.                                     'code': 'CMB',
    16.                                     'id_country': 'SRI',
    17.                                     'name': 'Bandaranayake'},
    18.                                    {'city': 'Belfast',
    19.                                     'code': 'BFS',
    20.                                     'id_country': 'UK',
    21.                                     'name': 'Belfast Intl'},
    22.                                     .....
    23. # Обратите внимание насколько все просто. Мы в 2 команды подключились к API и легко вызываем его методы - сразу получаем результат отпарсенный и подготовленный к работе в нашем языке.
    24. # Работать мне с ним так же легко и просто, словно это обычная библиотека на моем компе. 
      
# Для моей программы это абсолютно прозрачно.
    25. # Нас интересует табло прибытия за 15 число:
    26. import datetime
    27. date1 = datetime.date(2009, 11, 15)
    28.  
    29. arrival = api.Arrival(code='SVO', date=date1, order_field='airport', order='asc')
    30. arrival
    31. {'ArrivalResult': {'Flight': [{'airport': 'Adler/Sochi',
    32.                                'calc': (1, 1, 1,  0,  0,  0,  0,  0,  0),
    33.                                'company': 'SU',
    34.                                'fact': (1, 1, 1,  0,  0,  0,  0,  0,  0),
    35.                                'flight_no': '874',
    36.                                'flt_pk': '2009101359805123',
    37.                                'is_board':  0,
    38.                                'is_check':  0,
    39.                                'plan': (2009, 11, 15, 10, 55,  0,  0,  0,  0),
    40.                                'real': (1, 1, 1,  0,  0,  0,  0,  0,  0),
    41.                                'sched': (2009, 11, 15, 10, 55,  0,  0,  0,  0),
    42.                                'status': ''},
    43.                                ...... 


    
Wait, wait, but what about all this crap with XML, REST, passing parameters, parsing responses, and all the other attributes of a “cool” API? 
    
The film “The Matrix” responds best to this, a frame from which I wanted to put in the title:
     “There is no spoon, Neo.”

    
Just stop thinking about the spoon site API as something real, complex, you can begin to bend it comfortably to use. 
    
This is the enlightened API - transparent and bright so that you do not notice it when you work. For you, this is just a local library. And all the rest of the mechanics with network troubles occurs somewhere inside and does not bother you.

    How to distinguish a site API from shit.

    
I believe the attentive reader has already guessed? 
    
When instead of a simple, transparent and convenient work with the site’s API, you have to fool around with how to send a request to this site and why it doesn’t want to accept the request so carefully formed using curl, the output should be unambiguous. You got the wrong chocolate.

    conclusions

    
Nowadays, the presence of an API for a site claiming to be programmers, all kinds of integrations and so on are not a reason for pride, but a matter of prime necessity. But it’s not enough to make an API, even if you use the most fashionable principles - you need to make it convenient and transparent. And the data transfer technology here is of 10th importance - this is not necessary for the applied programmer at all. It should just take and use your library. 
    
If you want to get his attention, so that he spends his time integrating with you - take the first step - spend time on him. Give it a very simple and clear library. 
    
No need to blame that “we did as twitter - gave a REST-like interface”. You forget the main thing - Twitter has 5-10 libraries for each programming languagewhich you can simply download and use without bothering with the rest / xmlrpc / soap protocol. 

    
Good luck and have nice interfaces!
    Tags:
    

    
    
    
    
    Also popular now: