Как кратко назвать RESTful API, которое, оказывается, никакое и не RESTful, ибо возвращает JSON/XML, кодов HTTP-ошибок не использует, да и URLы не те?

Question

[VZVZ]

Вот всегда думал, что этакое привычное ныне API, возвращающее JSON (реже XML), не использующее (или почти не использующее) HTTP-кодов ошибок (вместо них - опять же все в JSON) и имеющее свободный формат URL, это и есть REST API, и оно же RESTful API.
Twitter тоже так думает:
https://dev.twitter.com/rest/public

А сегодня погуглил сей термин, почитал пару статей на хабре - и вижу там про какие-то паттерны URL наподобие /images/ и /images/1, про какие-то PUT и DELETE, про коды ошибок...
Оказывается, вон что изначально называлось REST.
И более того: погуглив "rest api json", вижу какие-то статьи, где пишут, будто если с JSON, то это вообще не REST API!

Вывод: не будем называть это REST API.

А что же взамен?
А взамен... Ничего.
Видел слово "JSON-pure API", но оно редкое, а что делать, если не только JSON, но и XML? Просто "Pure API"? Вообще не поймут, боюсь...

P.S. Еще один интересный вопрос: если REST API - это когда без JSON и XML (т.е. на HTML), то какое же оно тогда API?!
Это не API, а сыромятина какая-то, рассчитанная на браузер, а не на программиста, который под это все еще и писать будет.

Answer 1

[Станислав Макаров]

вижу какие-то статьи, где пишут, будто если с JSON, то это вообще не REST API!

если REST API - это когда без JSON и XML (т.е. на HTML), то какое же оно тогда API?!

Ссылки на статьи пожалуйста. Там либо автор фантазирует, либо его неправильно понимают. Единственная причина, по которой автор мог так заявить, это то, что большинство современных RESTful API не гипермедийные. Но это не значит, что не стоит в принципе использовать тот же JSON, это лишь значит, что нужно стремиться включить в него гипермедийные возможности (см. JSON-LD, HAL, Siren) и сам API также строить на этой идее, которая заключается в том, что у вас есть одна "точка входа", а на все остальные ресурсы, имеющиеся в API, вы попадаете, переходя по ссылкам внутри других возвращаемых ресурсов, точно также как вы заходите на сайт, зная его доменное имя, и дальше ходите по ссылкам.

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

не использующее (или почти не использующее) HTTP-кодов ошибок

А вот ошибками все-таки стоит пользоваться.

какие-то паттерны URL наподобие /images/ и /images/1, про какие-то PUT и DELETE, про коды ошибок...

RESTful API и MVC — что это?

Основной посыл использования RESTful API - применение основной идеи Паутины для взаимодействия автоматических агентов (приложений), а не только людей.

Основная идея Паутины - построение распределенной информационной системы путем публикации неких абстрактных ресурсов, выдачи им идентификаторов (в сегодняшнем вебе - иерархических), определения ряда простых и широко известных операций над ними, не зависящих от содержимого ресурса (те самые GET, POST, PUT и т.д.), и связывания этих ресурсов ссылками (это называется гипермедиа, и в частности, гипертекст, если речь идет о текстовой информации).

Таким образом, если вы хотите какую-то информацию опубликовать как RESTful API, вам необходимо представить ее как набор ресурсов, а все операции над этой информацией выразить через набор предопределенных операций. Фишка в том, что во многих задачах этих предпопределенных операций вполне достаточно, главное правильно определить ресурсы.

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

Видел слово "JSON-pure API"

Это уже вкусовщина. Люди не любят XML в API за то, что его модель подходит для описания иерархических данных и документов, но не для привычных объектно-ориентированных отношений между сущностями (он-то и создавался для представления документов, а не для веб-сервисов). Поэтому популярность JSON растет до упора. Многие старые API до сих используют XML, и JSON-pure - способ похвалиться, что ваше API полностью JSON. Сама идея RESTful ничего не говорит о форматах ответа, за исключением того, что формату желательно быть гипермедийным.

Comments

[VZVZ]

> включить в него гипермедийные возможности
Спс, глянем!

> Ссылки же одних ресурсов на другие используются редко.
Вы о чем? Можно пример таких ссылок?

> Многие старые API до сих используют XML
Еще не во всех языках в стандартной библиотеке есть средства для JSON.
Вот в C# (десктопном), насколько знаю, только для XML. Для JSON надо стороннее.
Вывод: в моем API будут и JSON, и XML, и еще HTML (как думаете, зачем?)

[Станислав Макаров]

VZVZ
> Вы о чем? Можно пример таких ссылок?
Пример для JSON-LD: json-ld.org/primer/latest , см. второй и третий фрагмент, св-во "category", представляющее из себя массив ссылок.
Пример для HAL можно увидеть по ссылке в ответе, чуть ниже. Там обратите внимание на спец. свойство "_links".

> Вот в C# (десктопном), насколько знаю, только для XML.
Ну Json.NET (www.newtonsoft.com/json) конечно стороння либа, но уже стала чуть ли не стандартной, ее уже и сами Майкрософты используют в ASP.NET. А без NuGet все равно уже сложно обойтись в средних и крупных проектах.

[VZVZ]

Станислав Макаров: и в чем смысл тех ссылок? Не врубаюсь.

[Станислав Макаров]

VZVZ пропустил тогда ваш комментарий, сейчас случайно зашёл. Вопрос еще актуален?

Answer 2

[Алексей Николаев]

REST Api базируется на одной-единственной вещи: наглядности ссылок, причем одна ссылка - одно действие. PUT \ DELETE редко используются потому, что они не везде поддерживаются, и для полной совместимости со всеми серверами и системами они заменяются POST \ GET соответственно.

И REST - не SOAP, который насквозь пропитан формализацией и протоколами (ынтерпрайз же), и должен возвращать только XML в определенном формате. REST API может отвечать так, как это требуется программисту, а json - едва ли не самый удобный способ ответа в 95% случаев.

Самое главное в REST - это структура самого API, которая должна быть чистой, наглядной и отвечать упомянутому выше требованию "одно действие - один запрос". Т.е., структура вида

/user/1/delete
/user/create
/user/1/getinfo

будет являться REST API, вне зависимости от того, какой формат будет отдавать сервер.

Ответ на вопрос: REST API.

Comments

[Roman K]

Добавлю, что JSON - лишь формат данных для обмена инфой. Там может быть хоть что вместо JSON. XML, base64, gzip'ованый tar.

[VZVZ]

Roman Kitaev: оффтоп.

[VZVZ]

Спасибо за мнение.

Но даже это требование:
> /user/1/delete
> /user/create
> /user/1/getinfo
не всегда соблюдают.

Или вот это (стиль VK):
/user.delete?id=1&access_token=blablabla
/user.create?access_token=blablabla
/user.get?id=1&access_token=blablabla
тоже называется REST API?

А если вот такая жесть:
/ajax.php?method=delete_user&id=1&access_token=blablabla
/ajax.php?method=create_user&access_token=blablabla
/ajax.php?method=user_get&id=1&access_token=blablabla
неужели тоже?

И главное, вообще-то я себе смысл REST API иначе представлял.
Думал, что REST API, это прежде всего когда с сервака можно запросить только сырые данные (JSON/XML/...), без всего лишнего, которые уже обрабатывает клиент. Если это не REST API называется, то как? AJAX не катит, клиент может и не быть веб-мордой.

[VZVZ]

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

[Алексей Николаев]

VZVZ: стиль VK как раз относится к REST, т.к. фактически, у них есть только /user.delete, /user.create и т.п., а дополнительные параметры, очевидно, зависят от типа запроса (исключая токен). В user.delete используется GET, поэтому там передается ID, а в create - уже POST, поэтому там только токен. Опять-таки, токен иначе, как через get, не передать, а перемещать его между POST и GET данными в зависимости от запросов как минимум странно и ведет к лишнему коду в месте его проверки.

А вот второй пример лично я бы к REST не отнес, т.к. требование о прозрачности URL на мой взгляд выполнено плохо.

> когда с сервака можно запросить только сырые данные
Ну так и запрашивайте, возвращаемые данные не зависят от API. Это ведь всего лишь интерфейс доступа (в данном случае).

> AJAX не катит
Тоже не имеет значения, только проверку придется поставить другую, чтобы рядовой пользователь не мог баловаться с адресами API без токена, например. При запросах через AJAX сырые данные просто посылаются в вывод при помощи echo.

[VZVZ]

Алексей Николаев: > а перемещать его между POST и GET данными в зависимости от запросов как минимум странно
Есть идея использовать HTTP-заголовок Authorization. Тот, что с base64.
Например, питонистам с библиотекой requests будет удобно, ИМХО.
Но зато сишарписты (читай: юзеры винды), такие, как я - вероятно, будут плеваться. К сожалению, у C# проблемы с HTTP-инструментарием все не очень хорошо, хоть и лучше, чем много где еще.
Вывод: в идеале надо оба варианта предусмотреть, ИМХО.

> возвращаемые данные не зависят от API
То есть даже если возвращает HTML, который на клиенте тупо ложится в innerHTML и все, то все равно это REST API?
Ну и как мне тогда выразиться, чтобы было понятно, что я говорю именно об удобной, современной реализации REST API, возвращающей именно JSON и/или XML, а уже потом HTML?
И что мне тогда предпочесть? Не совсем ясные словосочетания вроде "Cross-platform REST API"? Или ясное, но корявое слово "JSON REST API", напоминающее речь нубов, не понимающих, что к чему ("пишу скрипт на Ruby Jetbrains Rails")?

[Алексей Николаев]

VZVZ: по-хорошему, конечно, чистый html возвращать не стоит ни в одной из реализаций API (хотя в некоторых случаях это может быть быстрее, например, в пагинации), но в целом, REST это не нарушает. Суть в том, что это концепция, который охватывает большой спектр возможных реализаций, а не конкретный набор технологических решений (в отличие от того же SOAP).

> JSON REST API, Cross-platform REST API
Имхо, тут человек хотел донести мысль о "REST API, возвращающем JSON". Необязательно изобретать термины, можно просто уточнить русским языком все, что этого требует)

[VZVZ]

Алексей Николаев: > по-хорошему, конечно, чистый html возвращать не стоит ни в одной из реализаций API
Сотрудник Mail.Ru Group детектед. VK, Facebook, Google, да до кучи кто еще - с вами, видимо, не согласны в этом.

> Необязательно изобретать термины
Фары и ремень, однако.

Answer 3

[SirotaKazansky]

RESTful это то что соответствует ограничениям REST, никто не обязывает Вас использовать HTTP, какие-то форматы URL, методы HTTP, json или XML. Можете хоть на почтовых голубях сообщения отправлять в формате русского матерного, и сделать на их базе RESTful API