Как писать API?
=================

 Всем привет!  

  

Возникла задача написать API для общения приложения (ios) с базой данных. Опыта работы с php уйма, а вот api писать не приходилось. Хочется почитать про то как писать такую прослойку.  

  

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

  

В замен обещаю написать статью на эту тему :)  

  

Спасибо всем откликнувшимся! 

 1. Жесткая типизация и контроль входных и выходных данных. Много проблем получали, когда php-сервер отдавал string вместо int, например.  

2. Предусмотреть разный формат возвращаемых данных — json, xml и т.п. — на клиентсайде может оказаться не только ios.  

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

4. REST моден, но совершенно необязателен. После нескольких лет существования некоторых сервисов мы только сейчас начали вводить поддержку REST. Это нам не мешает разрабатывать популярные мобильные приложения на всех видах устройств.  

5. Изучите хорошие примеры сервисов и наоборот — ужасные примеры (Facebook). Никогда и ни за что не делайте, как у FB.  

6. Предусмотрите инструменты отладки.  

7. Сразу продумайте версионность. Выпустив однажды мобильное приложение уже нельзя будет просто поменять API.  

8. Можно сразу заложить инструменты кеширования и авторизации на уровень ядра API. Например, в одном приложении мы передавали oauth-токен в заголовках. Это позволило избавиться от постоянных проверок авторизации внутри модулей API, отдав это в родительские классы и управляя доступами через конфиги.  

И т.п. 

 Статей хватает, можете конечно написать, но врят-ли что-то-новое выйдет.  

  

Структуру методов, что и как должно возвращать лучше обсудите с iOS разработчиком, который будет потом имплеменить это дело. Если такого нету — максимально разбейте все на атомарные операции, упростите взаимодействие, прикиньте сами какие методы могут понадобиться (представьте что вы пишете API не для кого-то, а, например, для странички, которая через AJAX все выдерает).  

  

По поводу реализации — банальная сериализация вместо рендринга, больше отличий нету. Есть куча готовых компонентов которые хорошо подходят для сериализации туда и обратно. Свой такой компонент тоже пишется достаточно быстро.  

  

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

  

Я не видел ни одного RESTfull API для серьезных приложений, тобиш да, оно то REST но не полностью, так что заморачиваться тут не стоит. Достаточно просто обрабатывать какие-то базовые заголовки и GET/POST запросы. GET для выборок — тобиш данные в базе при запросе не меняются, разве что какие счетчики, а POST для создания записей в базе (по феншую результат работы функции должен возвращаться только HTTP заголовки, среди которых есть GET запрос с URI нового объекта, но на практике никто не париться и возвращает весь объект или его часть).  

  

Можно конечно воспользоваться SOAP апишками, но по опыту скажу что оно годно только при разработке оочень простых API, и толку от него мало. Если клиентом, конечно, будет приложение написанное на C# .NET — тогда смело SOAP и только SOAP, вам по сути разницы в реализации (имеется в виде по времени) минимум, а разработчику клиента будет намного проще. А вот на iOS с SOAP все достаточно печально. 

 В первую очередь почитай про принципы работы REST (ну или Soap, смотря что использовать будешь). Ну и опытом хабратоварищей можно воспользоваться:  

[Раз](http://habrahabr.ru/post/143317/)  

[Два](http://habrahabr.ru/post/150842/) 

 Есть очень хороший модуль для Node.js, у которого можешь подсмотреть интересные идеи реализации RESTful API, — [restify](http://mcavage.github.com/node-restify/). Также советую посмотреть как реализован API у [Amazon](http://docs.amazonwebservices.com/amazondynamodb/latest/developerguide/MakingHTTPRequests.html). Учти, что это реализации для enterprise использования, а реальной жизнь можно обойтись более простыми решениями, например отбросив ненужные http headers. 

 Насколько я знаю, наиболее популярной парадигмой создания API на данный момент является [REST](http://en.wikipedia.org/wiki/Representational_state_transfer)  

Об опыте создания API на вскидку нашёл следующие статьи: [1](http://stackoverflow.com/questions/1950204/how-do-i-structure-a-real-world-api-according-to-rest-principles), [2](http://viswaug.wordpress.com/2008/09/08/why-is-it-important-to-follow-restful-principles-when-developing-a-rest-api/).  

  

По опыт скажу, что тут важнее всего грамотно всё спланировать. Найдите проект по возможности сходный с Вашим целевым который предоставляет документацию по своему API, и почитайте её. 

 Вот тут ОЧЕНЬ хорошая статья о том, как правильно писать REST API:  

[blog.mugunthkumar.com/articles/restful-api-server-doing-it-the-right-way-part-1/](http://blog.mugunthkumar.com/articles/restful-api-server-doing-it-the-right-way-part-1/)  

очень рекомендую.