Этот вопрос охватывает очень большую область, и я сомневаюсь, что какой-либо один ответ может охватить вопросы в деталях. Что я могу сделать, так это предложить некоторые отправные точки, основанные на допущенных мной ошибках.
Сборка поверх собственного 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-only для выполнения каких-либо действий, прежде чем переходить на собственное решение.
Хотите, чтобы пользователь указал, должен ли формат ответа быть XML или JSON? Используйте заголовок HTTP Accept.
Хотите перенаправить клиента на другой URL-адрес, чтобы получить результат запроса? Используйте заголовок HTTP Location.
Существует множество функций HTTP, которые уже обрабатывают многие вещи, которые вы, возможно, захотите сделать. Используйте их!
Безопасность
Здесь необходимо решить две основные проблемы: аутентифицировать пользователя и определить, какие действия может выполнять данный пользователь.
Безопасность: аутентификация
Пользователь должен будет указать в своем запросе, кто он такой.
Первое решение, которое приходит на ум - позволить пользователю указать имя пользователя и пароль, возможно, такие же, как имя пользователя и пароль, которые они используют для доступа к вашему приложению. На первый взгляд, это хорошая идея, но она не идеальна.
В конечном итоге пользователи будут добавлять свои имя пользователя и пароль в свои приложения. Неизбежно один пользователь забудет свой пароль и изменит его так, чтобы он мог счастливо получить доступ к вашему приложению, нарушая в процессе свое собственное приложение.
Лучшим вариантом было бы предоставить пользователю токен аутентификации, который, по сути, представляет собой единственное уникальное для пользователя значение, такое как имя пользователя и пароль, объединенные в одно.
Это позволяет логически отделить имя пользователя и пароль от доступа к API. Пользователь может изменять свое имя пользователя и / или пароль для вашего приложения так часто, как ему хочется, не нарушая доступа к API.
Пользователь также может иметь несколько токенов API, каждый из которых имеет разные уровни доступа, что позволяет пользователю безопасно выдавать токен API сторонней службе.
Безопасность: контроль доступа
Что касается внешнего мира, ваш API - это набор URL. Каждый URL по определению уникален и выполняет уникальную задачу. Использование этих механизмов контроля доступа на основе этих концепций является хорошей отправной точкой.
Я предпочитаю хранить список URL-адресов, к которым токену разрешен доступ. Когда данный токен используется для доступа к URL-адресу, тривиально определить, к какому URL-адресу обращаются и находится ли он в списке разрешенных URL-адресов токена.
Если вы разумно выберете набор URL-адресов, где каждый URL-адрес выполняет одно уникальное действие, этот процесс обеспечит вам наилучший уровень контроля доступа, который вы получите.
Чтобы обеспечить более высокий уровень контроля, вы также можете указать, для каждого URL, к которому разрешен токен, какие аргументы запроса им разрешено использовать.