Каковы некоторые подводные камни / советы, которые можно было бы дать при разработке веб-службы?

Question

Мы хотим разработать веб-сервис (API) на PHP, чтобы предложить клиентам более простой способ интеграции с нашей платформой.Существуют вызовы рабочего процесса, которые будут проверяться пользователем / паролем, а также некоторые параметры отчетов.

Извините, я не могу опубликовать более подробную информацию или код по этому вопросу, и у меня никогда не было веб-службы, но у меня был опытпри использовании их через SOAP.

Теперь мне также нужно предложить состояние или статус рабочего процесса, и я думаю, что REST будет лучшим выбором, но все еще ищу мнения по этому поводу.

Для составления отчетов я хотел бы предложить различные варианты, такие как XML, Excel / CSV, по любой причине, по которой я бы выбрал один из них?

На какие подводные камни я должен обратить внимание?

Какие драгоценности может предложить каждый.

Заранее благодарен за любую помощь, поскольку это очень важно для меня понять.

ОБНОВЛЕНИЕ № 1:

• Какой метод будет наиболее безопасным?
• Какой метод наиболее гибкий (не зависит от платформы)

ОБНОВЛЕНИЕ №2: немного о потоке данных.У каждого пользователя есть права на использование API, и данные не передаются между пользователями.Пользователь использует запрос, запрос обрабатывается и возвращается.нет обновлений.(Подумайте гугл) сделан поисковый запрос и даны результаты, но в моем случае дается только один результат.Не знаю, нужно ли это, так что это к вашему сведению.

Answer 1

Always handle errors and exceptions.

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

Также, если ваш сервис будет обрабатывать много запросов и для одного и того же идентификатора ресурса (независимо от пользователя) возвращается тот же ресурс, обязательно кешируйте информацию. И это не только из-за соображений производительности, но и для случаев, когда возникают ошибки. Таким образом, вы, по крайней мере, можете что-то подать клиенту (возможно, полезно, требуется больше контекста, чтобы быть явным).

Answer 2

Хорошо предлагать несколько выходов, таких как JSON, CSV, YAML или XML, - это дает конечному пользователю комфорт при очень небольших затратах! Выгрузка данных всегда проще, чем обработка, и говорят, что по какой-то причине они уже анализируют JSON - гораздо проще просто подключить это к вашему API, чем реализовать, скажем, XML-парсер. В настоящее время я вижу повсюду XML-парсеры, так что это, вероятно, не должно быть проблемой, но мне нравится более "воздушная" природа JSON; Я немного посмотрел на YAML, но никогда не использовал его - но он выглядит многообещающим, я определенно буду использовать это для файлов конфигурации моего следующего проекта.

Что касается безопасности всего, что динамически обрабатывает любой ввод, который дает пользователь, то к такому вводу следует относиться как к чему-то, что вы бы не совали даже палкой.

ИМХО REST без сохранения состояния лучше, чем SOAP, поскольку он требует меньших накладных расходов, можно легко связаться с REST-api вручную, используя curl или wget из терминала. Старт, так сказать.

Я бы порекомендовал вам сделать глубокий вдох, карандаш и бумагу, сесть и набросать все, что будет необходимо. Затем вы удаляете менее важные вещи, берете новую бумагу и начинаете ее организовывать. Вы можете добавить менее важные вещи в следующую версию API.

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

Answer 3

Немного больше связано с реализацией, чем с дизайном: я бы решил, что вывод сервиса должен быть XML - это может быть очень легко проанализировано всеми приличными языками.Кроме того, если для какого-либо клиента требуется другой вывод, вы можете преобразовать эти XML через некоторые процессоры XSLT и предложить «другие» веб-сервисы, которые выводят JSON, или все, что им нужно.Что касается отчетности, это зависит от того, как отчеты будут использоваться - если клиенты обрабатывают их и им нужны только данные из отчетов, - тогда снова предложите XML.По моему мнению, работать с CSV сложнее, потому что вы должны принять во внимание все виды особых случаев, таких как «что произойдет, если мои данные содержат поле разделителя», «сможет ли клиент указать разделитель», «как я буду представлятьвложенные данные ", или все они прямо с XML.Если вашему клиенту нужны отчеты, чтобы использовать их из коробки, вы можете использовать BIRT - красивый и бесплатный

Answer 4

В настоящее время я работаю над веб-приложением, которое включает веб-службу (или 2 в ASP.NET MVC), и я настоятельно рекомендую взглянуть на принципы, лежащие в основе сервис-ориентированной архитектуры (SOA), поскольку я обнаружил, что наиболее важнымАспект заключается в том, чтобы правильно спроектировать API веб-службы, поскольку это повлияет на остальную часть вашего бэкенда и либо облегчит вашу жизнь, либо заставит вас разочароваться в стенах.

По сути, SOA означает проектирование сетиобслуживание вокруг бизнес-процессов, то есть то, как люди, которые используют ваш API, вероятно, будут его использовать.

Хороший дизайн - это всегда хорошая идея, поэтому я настоятельно рекомендую вам много прочесть о принципах дизайна Web-сервиса, прежде чемВы начинаете кодировать и спасаете себя или какой-либо другой несчастный случай.

Также убедитесь, что ваш дизайн является гибким, поскольку он будет часто меняться, когда происходит общение между вашей компанией и вашими клиентами.

Answer 5

Самая большая и самая важная вещь, которую я могу предложить, - это гарантировать, что ваша инфраструктура за WS или, по крайней мере, то, что вы обслуживаете через WS, не имеет состояния. В тот момент, когда вы отклонитесь от этого, это станет кошмаром, и вы начнете вводить код, чтобы защитить ваши данные от фальсификации.

Примером могут служить два клиента, которые вносят изменения в данные через WS, т. Е. ... сохраняют конфигурацию. То, как вы справляетесь с этим на заднем плане, делает вещи интересными. Если ваши данные только отправляются в исходящее положение, вы находитесь в гораздо лучшем положении, чем если бы вам пришлось поддерживать передачу данных в серверную часть.

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