Документация к SOAP API. Нужна ли она и справедливо ли возражение о том, что WSDL достаточно?
Добрый вечер, пользователи Тостера.
Я хотел бы услышать ваше мнения по поводу ситуации, описанной ниже.
Есть компания А - бизнес, компания Б - разработчики БД для бизнеса и приложений для кассиров бизнеса, компания В - разработчик веб-сайта для компании А, который должен получить содержимое БД, которую сейчас использует бизнес.
Я программист, фрилансер, работаю с компанией В и делаю всю программную часть сайта. И сайт должен выгрузить содержимое БД, которую разрабатывает компания Б. Программисты компании Б должны были написать API для общения наших двух систем.
Спустя 2 недели после дедлайна, они сделали API, но без документации. Менеджер компании Б сказал, что WSDL должно быть достаточно для понимания. Я не согласился и попросил предоставить хотя бы пример кода. Потом это переросло в спор.
Немного сути АПИ: 2 запроса на получение данных. Второй имеет 3 параметра: shopID (суть понятна из названия, значение получаем с первого запроса), дата и булевый параметр. У меня не получилось угадать со вторыми параметрами. Да, спустя 6 часов переговоров я получил кусок кода и подстеб со стороны менеджера из-за того, что я не смог угадать параметры.
После дискуссия продолжилась:
>>> для АПИ пишется документация.
вы не можете найти документацию на SOAP ? я не понимаю зачем вы у меня требуете то что, лежит в свободном доступе и разрабатывалось не нами.
Нет, в принципе, если бы я смог выполнить свою работу, то я бы не парился и не писал бы этот текст. Просто фишка в том, что в итоге то API оказалось неполноценным и нам еще предстоит совместная работа. Собственно вопрос в том, адекватно ли возражение со стороны менеджера компании Б, приведенное выше, или я должен был получить документацию?
P.S.: неправильно предположив значения параметров (name=dt type=xs:dateTime и name=firstTime type=xs:boolean) я не получил ожидаемого результата
Ну обычно на wsdl натравливается парсер который строит классы клиента. Технически это позволяет уже общаться с сервисом. Но все таки этого может быть недостаточно - надо же знать какая функция для чего нужна. WSDL это все таки не документация, а просто описание, метаданные.
Послать такого менеджера нужно на... курсы по WSDL, в частности, чтоб про "wsdl:documentation" узнал и устыдился. А вообще, типы параметров, определенные WSDL - это, как бы, одно, а вот их предназначение - совсем другое. Уважающие себя разрабы ко второму не только пишут доку в WSDL, но могут даже нарисовать UML и написать текст с примерами, если логика интерфейса требует этого ввиду своей нетривиальности.
P.S. Впрочем, самоуважение, как и профессионализм, не относятся к ключевым скилам среднестатистического современного менеджера :)
WSDL достаточно, по нему генерируется код, в нем есть вообще все все все что нужно для работы с API. Документация нужна только если у вас море методов и все они делают какие-то сложные вещи не очевидные из названий.
Сергей Протько: не возвращало данных. Там нужно было проставить $date = '2015-01-01T00:00:01Z'; $firstTime = 'true'; По логике, которую мне позже предоставили, это должны быть товары, измененные после некой даты, если второй параметр false. Булевой параметр true значит, что обращение по данному магазину идет впервые, то есть нужно выгрузить все товары. Это типа полиморфизм.
Денис Драгомирик: ну по поводу даты - SOAP использует iso 8601, обычно никто вообще не парится так как генераторы кода из wsdl это учитывают и формируют нормальный объект. Ну или умеют объект date time преобразовывать сразу в этот формат. Между прочим это самый распространенный пожалуй формат обмена датами и временем в сети.
Что до булена - тут надо знать что вообще делает api но по смыслу вроде подходит.
Сергей Протько: "тут надо знать что вообще делает api" - у меня было понимание только исходя с задачи: "получение списка товаров". Просто чтобы Вы понимали $date = '1970-01-01T00:00:01Z'; - не работает. Изначально у меня не было никакого представление ни о структуре данных, ни о схеме работы, ни об описании интерфейса.
Я уже выше писал, что неправильно предположив значения параметров (name=dt type=xs:dateTime и name=firstTime type=xs:boolean) я не получил ожидаемого результата. В WDSL ведь описывается только интерфейс взаимодействия, а в данном примере имела место еще и логика.
Александр: xs:complexType name=getProductListRequest . Одно дело, если бы это было бы очевидно. Но тут ведь навскидку объяснить, что должен получить метод - сложновато
Александр: $date = '2015-01-01T00:00:01Z'; с этим работает. Ссылку, к сожалению, не могу дать - это корпоративная информация, а API реализовано без дополнительного уровня защиты
Александр: да нет) Мой вопрос заключался в споре с менеджером. Сейчас у меня есть рабочий код текущей версии АПИ, но изначально его не было, и не было ответа вообще - была ошибка. Ну из-за этого с ссорился с менеджером компании, которая это АПИ делала - я утверждал, что WSDL недостаточно для понимания самой логики. А угадывать параметры является тратой времени - это я пытался тебе объяснить, потому что думал, что ты дискутируешь в аспекте того, что по интерфейсу всегда можно понять логику :)
Александр: а если я передам в параметре shopId значение 32? Да, я заранее знаю, что при прочих равных это решение не будет работать - я просто хочу донести мысль о необходимости хоть каких-либо комментариев для интерфейса.
Поймите одно - в WSDL, как и все схеме XSD(составляющая WSDL) описаны допустимые значения передаваемых параметров.
Если вы передали все верно и приходит отчет от сервиса с непонятной ошибкой - это совершенно другое. Документировать описание ошибок или их расшифровку они должны, на этом можно настоять. Но описание параметров запроса не стоит, т.к они все есть в выше перечисленных схемах.
У разработчиков ТЗ точно не было. Но менеджер имел достаточно однозначную задачу - сделать АПИ, с помощью которого можно получить все товары и с помощью которого можно проверять, изменились ли данные. Это они должны были сделать еще год назад, но сделали "на коленке", хотя, в принципе, задача тривиальная. Но параметры методов интерфейса уже готового АПИ неочевидны
Средний
Средний