Каковы параметры обработки флагов и атрибутов в REST API?

Question

Предположим, у вас есть сложный ресурс в REST API. У вас есть несколько флагов и атрибутов «один ко многим» на этом ресурсе (т. Е. Пользователь может присвоить ресурсу рейтинг от 1 до 5, или пользователь может «понравиться» ресурсу или помечен как спам или проигнорировать его или вызвал некоторое другое состояние, которое нужно установить).

Некоторые предложения были сделаны для наилучшего представления этого в ресурсо-ориентированной архитектуре, но пока никто из них не сделал меня счастливым. Так что давайте толпу-источник это; какие варианты вам легче понять? Какие варианты мы не думали? Предположим, что API, основанный на OAuth, и все здесь сделано в контексте авторизованного пользователя.

• булевы Флаги

  • Вариант 1:

     
    GET /resource/{id}/muted 
    POST /resource/{id}/muted BODY:true 
    POST /resource/{id}/muted BODY:false 
    

  • Вариант 2:

     
    GET /resource/{id}/muted 
    PUT /resource/{id}/muted BODY:true 
    DELETE /resource/{id}/muted 
    

  • Вариант 3:

     
    GET /resource/{id}/attributes 
    POST /resource/{id}/attributes BODY:muted=true 
    POST /resource/{id}/attributes BODY:muted=false 
    

  • Вариант 4:

     
    GET /resource/{id}/muted 
    POST /resource/{id}/mute 
    POST /resource/{id}/unmute 
    

• Атрибуты

  • Вариант 1

     
    GET /resource/{id}/rating 
    POST /resource/{id}/rating BODY:4 
    

  • Вариант 2:

     
    GET /resource/{id}/rating 
    PUT /resource/{id}/rating BODY:4 
    DELETE /resource/{id}/rating 
    

  • Вариант 3:

     
    GET /resource/{id}/attributes 
    POST /resource/{id}/attributes BODY:rating=4 
    POST /resource/{id}/attributes BODY:rating= 
    

Мысли? Предложения? Как другие API обрабатывали это? Как вы справились с этим? Вы обнаружили, что такие проблемы дизайна повлияли на счастье разработчиков или простоту использования ваших API?

Answer 1

От Roy's dissertation:

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

Так что вам нужен вариант 5, который работает как для флагов и других атрибутов:

GET /resource/{id}/ BODY:{muted: false, like: false, rating: 2, ignored: true} 
POST /resource/{id}/ BODY:{muted: true, like: false, rating: 2, ignored: true} 
POST /resource/{id}/ BODY:{muted: false, like: false, rating: 2, ignored: true} 

Одной из главных причин является то, что большинство эффективность RESTful HTTP-приложения исходит из кеширования, и это лучше всего работает, когда его артефакты имеют как можно большее зерно, и когда его данные достижимы с минимальным количеством идентификаторов. Если вы выставляете флаг «приглушенный» как на /resource/{id}/, так и на /resource/{id}/muted, у вас есть проблема с недействительностью кеша. Если вы выставите его только на /resource/{id}/, то вы этого не сделаете.

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

Answer 2

Мне нравится Вариант 3, если я могу предоставить кучу сразу - в противном случае, я равнодушна между 1 и 3.

И, определенно ничего, что использует DELETE.