Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живёте.

Всем привет!

Я работаю тимлидом команды Integration Development в сервисе онлайн-бронирования отелей Ostrovok.ru и сегодня хотел бы поделиться своим опытом работы с различными API.

Как разработчик системы, работающей с внешними поставщиками, я часто встречаюсь с различными API – чаще всего это SOAP/REST или что-то на них похожее. Однако от работы со многими из них остается впечатление, что их писали, не руководствуясь ни техническими правилами, ни здравым смыслом – как будто бы по книге “Вредные советы” Григория Остера. В данной статье я постараюсь описать такие случаи в стиле “вредных советов” и рассмотрю примеры, связанные с XML. Комментарии и обсуждение приветствуются.

Историческая справка

SOAP (от англ. Simple Object Access Protocol – простой протокол доступа к объектам) – протокол обмена структурированными сообщениями в распределённой вычислительной среде. Первоначально SOAP предназначался в основном для реализации удалённого вызова процедур (RPC). Сейчас протокол используется для обмена произвольными сообщениями в формате XML, а не только для вызова процедур.

Переходим к примерам

1. Передача xml в url

Чего больше всего хотят пользователи API? Конечно же, простоты, надёжности и лаконичности. Так давайте не будем читать тело запроса, а будем принимать XML как url-encoded информацию как параметр пути запроса! Что может быть лучше:

http://exapmple.com/xml/form.jsp?RequestName%3DHotelRequest2%26XML%3D%3C%3Fxml%2Bversion%3D%221.0%22%2Bencoding%3D%22UTF-8%22%3F%3E%0A%3CHotelRequest2%2BBuyerId%3D%22test%22%2BUserId%3D%22test%22%2BPassword%3D%22test%22%2BLanguage%3D%22en%22%2BHotel%3D%22-100%22%2BProductCode%3D%221--%22%2BArrivalDate%3D%2223.12.2018%22%2BDepartureDate%3D%2224.12.2018%22%2BArrivalTime%3D%22%22%2BDepartureTime%3D%22%22%2BCurrency%3D%222%22%2BWhereToPay%3D%223%22%2BNumberOfGuests%3D%220%22%2BNumberOfExtraBedsAdult%3D%220%22%2BNumberOfExtraBedsChild%3D%220%22%2BNumberOfExtraBedsInfant%3D%220%22%2B%2F%3E

Всё становится просто, и не надо вычитывать какое-то тело из запроса – мало ли, какие с ним могут быть проблемы.

2. Передача информации путём избыточной вложенности объектов данных

Давайте подумаем, как бы сделать информацию в ответах как можно более сложнодоступной? Давайте использовать вложенные структуры, да ещё и в разных форматах! Сказано, сделано —

<Request>
    <InnerRequest>
        <RQ>[{"someInfo":"base64Data"}]
</RQ>
    </InnerRequest>
</Request>

Действительно, верхнеуровневый xml, внутри него ещё один xml, а внутри него json, в котором данные представлены в base64, а в нём снова json, и в нём уже будет нужная нам информация! Прекрасное решение, практически как из сказки про смерть Кощея, спрятанную в яйце.

3. Добавление информации, не относящейся к данным запроса и не допустимой в рамках формата данных

Предположим, к нам в теле запроса приходит XML, мы обрабатываем его и даем ответ. Выглядит слишком сложно для хорошо продуманной и высоконагруженной системы. Давайте обязуем пользователей присылать тип данных в теле запроса. Как же это сделать? Прямо в теле запроса, конечно же.

XML=
<Request>
...
</Request>

Вот таким простым способом мы всегда будем знать, что нам пришёл запрос в формате XML.

4. Дублирование данных без необходимости

Предположим, у нас в структуре XML ответа есть очень-очень важная информация. Как показать это пользователю? Самое очевидное – давайте покажем её несколько раз в рамках ответа, тогда он точно обратит на неё внимание.

<Response>
    <Obj Info="Important">
        <ObjSetting Info="Important"/>
        <Name>SomeName</Name>
        <Info>Important</Info>
    </Obj>
</Response>

После этого конечный пользователь точно обратит внимание на поле Info.

5. Передача параметров одного типа по отдельности, а не массивом

Во одном из API, которые мы используем для поиска отелей, есть поля, обозначающие возраст гостей. Какой формат представления лучше всего использовать для передачи этой информации? Пусть формат будет таким: каждый возраст будет отдельным обязательным тегом XML, и значение 0 мы будем считать, как отсутствие этого параметра.

<Request>
<Age1>20</Age>
<Age2>20</Age>
<Age3>0</Age>
<Age4>0</Age>
</Request>

6. Пересылка информации из предыдущих запросов в рамках цепочки вызовов API

Самое время подумать о безопасности нашего API. Как мы поймём, что пользователь получает информацию из наших предыдущих ответов? Пусть он присылает нам наш ответ, конечно же!

<Request>
    <RequestInfo/>
    <PreviosResp>
    ...
    </PreviosResp>
</Request>

7. Неиспользование маркеров случившейся ошибки, таких как тег ошибки или http-код

Мы сделали наш прекрасный API и представили его миру. Но однажды что-то пошло не так, и мы не смогли сформировать ответ пользователю из-за внутренней ошибки. Что делать в таком случае? Просто дать шаблон ответа, без данных, без кодов ошибок или какой-либо другой информации. Никто не должен знать, что наш идеальный API может порой не работать!
Пример такого ответа:

<Response>
    <ImportantInfo/>
</Response>

– с кодом ответа 200 OK.

Заключение
Несмотря на большое количество документации по работе с технологиям SOAP/XML и проектированию API, многие проблемы всё ещё актуальны, и некоторые решения противоречат здравому смыслу. Надеюсь, этой статьей мне удастся обратить внимание разработчиков на не самые удачные подходы, чтобы уменьшить их количество в будущем.