Этот вопрос охватывает очень большую площадь, и я сомневаюсь, что какой-либо один ответ мог бы подробно осветить вопросы. Я могу сделать несколько отправных точек, основанных на ошибках, которые я сделал.
Построить на вершине собственного API
Не добавляйте в особенности API к существующей системе. Это позволит:
- приводит к дополнительной нагрузке тестирования (вы должны проверить, как приложение и API независимо друг от друга)
- результата в увеличении общих эксплуатационных расходы
- результата в более низком качестве API чем вы хотите предложить
Ваша общая цель должна заключаться в том, чтобы сначала создать API, а затем создать приложение поверх своего собственного API. Это имеет следующие преимущества:
- тестирование API неотъемлемо выполняется во время тестирования приложение
- вы не «забыть», чтобы добавить любые необходимые методы API
Ваше приложение и ваш логика приложения (API) будет логически разделена - между ними будет четкое разделение с точки зрения того, что делает каждая сторона уравнения и за что оно отвечает. Это поможет вести разработку. Это также позволит вам очень легко разместить приложение и API на разных машинах по мере необходимости.
Использование вашего собственного API - очень важный момент. Первоначально дизайн вашего API будет субоптимальным, и только используя его самостоятельно, вы сможете сделать его доступным людям, которые на самом деле нужны, таким образом, чтобы это было эффективно.
Вы будете в конечном итоге с системой, которая примерно выглядит следующим образом:
------------- -------------
| | | |
| Your APP | <= HTTP communication => | Your API |
| | | |
------------- -------------
Это выдвигает на первый план некоторые дополнительные преимущества: вы можете заменить «Ваше приложение» с любым другим приложением, что позволяет клиентам твои создавать приложения для иметь дело с вещами, которые лучше всего работают с ними. Вы также можете создавать новые версии своего приложения поверх существующего API - переход на новую версию вашего общедоступного веб-сайта может быть намного проще.
Проектирование ваших URL-адресов: отображение на классы и методы
Выбор осмысленные URL, как большая проблема, как выбрать осмысленные имена классов и методов. Вывод URL-адресов из классов и их методов является хорошим подходом. Если нет разумной корреляции между URL-адресами и классами/методами, в долгосрочной перспективе вам будет сложнее поддерживать.
Я лично предпочитаю, чтобы связать URL-адрес для классов и методов следующим образом:
- карты классов в каталоги верхнего уровня
- методу карты в подкаталоги каталогов верхнего уровня
Пример:
URL вашего API: https://api.camerareadyart.com.
У вас есть объект image с toColour() и toBlackAndWhite() методов.
Это может сопоставить:
https://api.camerareadyart.com/image/toColour/
https://api.camerareadyart.com/image/toBlackAndWhite/
Аналогично для растрового изображения в векторное преобразование:
https://api.camerareadyart.com/bitmap/toVector/
ответы Проектирование
Когда кто-то получает данные из или сообщения данных, чтобы один из ваших URL-адреса, что происходит? Как обрабатываются ошибки, как делаются исключения? Какую форму принимают ответы?
Я не могу сказать вам, что делать здесь. Лично я предпочитаю сопоставлять вещи так близко к HTTP, насколько это возможно, а затем только выходить за рамки этого, когда это необходимо.
Например, если входящий запрос принят и обработан, но во внутреннем ящике возникает ошибка, я выдал бы ответ на состояние 500. Аналогично, если для данного метода API требуется проверка подлинности, которая не была предоставлена, я могу опубликовать 403. Использование существующих функций HTTP не позволяет вам повторно изобретать определенные вещи.
Использовать существующие аспекты HTTP
а также с использованием кодов статуса HTTP здраво, убедитесь, чтобы осмотреться для HTTP-единственный метод для делать что-то перед прокаткой собственное решение.
Хотите, чтобы пользователь указал, должен ли формат ответа XML или JSON? Используйте заголовок HTTP Accept.
Хотите перенаправить клиента на другой URL-адрес, чтобы получить результат запроса? Используйте заголовок HTTP Location.
Существует множество функций для HTTP, которые уже обрабатывают многие вещи, которые вы, возможно, захотите сделать. Используй их!
безопасности
Есть две общие проблемы по решению проблемы здесь: проверка подлинности пользователя, и определение, какие действия данный пользователь может выполнять.
Безопасность: аутентификация
Пользователь должен указать в своей просьбе, кто они есть.
Первое решение, которое нужно учитывать, - дать пользователю возможность указать имя пользователя и пароль, возможно, такие же, как имя пользователя и пароль, которые они используют для доступа к вашему приложению. Это кажется на первый взгляд хорошей идеей, но это не идеально.
Пользователи в конечном итоге выпекают свое имя пользователя и пароль в свои собственные приложения. Неизбежно один пользователь забудет свой пароль и изменит его, чтобы они могли с радостью получить доступ к вашему приложению, нарушив собственное приложение в этом процессе.
Лучшим выбором для пользователя будет предоставление токена аутентификации, который по существу является единственным значением, уникальным для пользователя, так же как имя пользователя и пароль, сгруппированные в один.
Это позволяет логически отделять имя пользователя и пароль от доступа к API. Пользователь может изменить свое имя пользователя и/или пароль для вашего приложения так часто, как им нравится, не нарушая их доступа к API.
Пользователь может также иметь несколько маркеров API, каждый с разными уровнями доступа, что позволяет пользователю безопасно выдавать маркер API сторонней службе.
безопасность: контроль доступ
Что касается внешнего мира, то, ваш API представляет собой набор URL. Каждый URL по определению уникален и выполняет уникальную задачу. Хорошей отправной точкой является создание механизмов контроля доступа вокруг этих концепций.
Я предпочитаю хранить список на каждый токен URL-адресов, которым разрешен доступ к токену. Когда данный токен используется для доступа к URL-адресу, тривиально указывать, к какому URL-адресу обращаются и находится ли он в списке разрешенных URL-адреса.
Если вы выбрали набор URL-адресов с умом, где каждый URL-адрес выполняет одно уникальное действие, этот процесс предоставляет вам самый лучший уровень контроля доступа, который вы собираетесь получить.
Чтобы дать более высокий уровень контроля, вы также можете указать, на какой URL-адрес разрешен доступ к токену, какие аргументы запроса разрешены им использовать.
Спасибо за такой информативный ответ. Это означает, что я должен реализовать API в качестве веб-службы. Потому что только веб-сервис сможет выставить API, и пользователь сможет подключиться через него. Я прав, или есть другой способ? Как будет доступна веб-служба. Будет ли компания-хостинг делать какие-либо изменения на сервере? –
Веб-сервис, вероятно, лучший вариант для веб-продукта. Не требуется никаких явных изменений для хостинговой компании.В идеале ваше приложение и ваш api должны находиться на разных хостах (разные IP-адреса, логически или физически). Ничего не требуется, чтобы сделать веб-сервис доступным, чем потребуется для создания веб-сайта. Единственное различие заключается в том, что данный URL-адрес возвращает не веб-страницу, а какой-то машинный формат ответа, такой как XML или JSON-индикация результата запроса. –
Джон, Спасибо за ваш ценный вклад. Теперь я понимаю большую часть того, что мне нужно делать. Кстати, сайт уже работает, единственное, что он еще не размещен. Он находится на сервере тестирования нашей компании. Мы испытываем стресс. Предполагалось, что он начнет действовать 1 октября 2009 года, но внезапно наш клиент попросил эту функцию API. Так вы и не указали (Первый API, а затем Разработка). Это наоборот :). Еще раз спасибо –