rest - sustantivos - Confusión entre el sustantivo y el verbo en las URL de reposo

verbos http rest (3)

He estudiado a través de Internet sobre API tranquilas que se centran en los sustantivos y no en los verbos en el patrón de url, pero ahora estoy viendo múltiples enlaces que usan verbos en la URL.

Aquí hay un ejemplo.

POST / v1 / pagos / autorización / <Authorization-Id> / capture
POST / v1 / pagos / autorización / <Autorización-Id> / void
POST / v1 / pagos / autorización / <Authorization-Id> / reautorizar

esto es paypal apis. API de PayPal

también en wikipedia en la página de HTATEOAS dieron un ejemplo;

<?xml version="1.0"?> <account> <account_number>12345</account_number> <balance currency="usd">100.00</balance> <link rel="deposit" href="/account/12345/deposit" /> <link rel="withdraw" href="/account/12345/withdraw" /> <link rel="transfer" href="/account/12345/transfer" /> <link rel="close" href="/account/12345/close" /> </account>

enlace: Wiki HATEOAS

¿Alguien puede ayudarme a obtener algo de claridad sobre esto? ¿Por qué ''captura'', ''vacío'', ''depósito'', ''retirar'', ''cerrar'' están en el URI porque son verbos y no sustantivos?

o ¿está bien usar este tipo de palabras en la URL apis llena de descanso?

Algunos fragmentos del libro de reglas de REST API Design sobre diferentes tipos de recursos:

Documento
Un recurso de documento es un concepto singular que es similar a una instancia de objeto o registro de base de datos.
Ejemplo: http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet
Colección
Un recurso de colección es un directorio de recursos administrado por el servidor. Los clientes pueden proponer nuevos recursos para ser agregados a una colección. Sin embargo, depende de la colección elegir crear un nuevo recurso, o no.
Ejemplo: http://api.soccer.restapi.org/leagues/seattle/teams
Almacenar
Una tienda es un repositorio de recursos administrado por el cliente. Un recurso de la tienda permite que un cliente de la API ingrese recursos, los recupere y decida cuándo eliminarlos. Por su cuenta, las tiendas no crean nuevos recursos; por lo tanto una tienda nunca genera nuevos URIs. En su lugar, cada recurso almacenado tiene un URI que fue elegido por un cliente cuando se colocó inicialmente en la tienda.
Ejemplo: PUT /users/1234/favorites/alonso
Controlador
Un recurso controlador modela un concepto de procedimiento. Los recursos del controlador son como funciones ejecutables, con parámetros y valores de retorno; entradas y salidas.
Al igual que el uso de formularios HTML de una aplicación web tradicional, una API REST se basa en los recursos del controlador para realizar acciones específicas de la aplicación que no pueden asignarse lógicamente a uno de los métodos estándar (crear, recuperar, actualizar y eliminar, también conocido como CRUD).
Los nombres de los controladores suelen aparecer como el último segmento en una ruta de URI, sin recursos secundarios para seguirlos en la jerarquía.
Ejemplo: POST /alerts/245743/resend

Según las definiciones en el libro, los URI que has publicado probablemente caen bajo el tipo de recurso Controlador , del cual el libro más adelante establece:

Regla: se debe usar un verbo o frase verbal para los nombres de los controladores
Ejemplos:
http://api.college.restapi.org/students/morgan/register

http://api.example.restapi.org/lists/4324/dedupe

http://api.ognom.restapi.org/dbs/reindex

http://api.build.restapi.org/qa/nightly/runTestSuite

Otras reglas de nomenclatura, solo para completar

Regla: un nombre singular debe usarse para nombres de documentos
Regla: un nombre plural debe usarse para nombres de colecciones
Regla: un nombre plural debe usarse para nombres de tiendas

El truco es hacer que todos los nombres (o entidades) que operan con los verbos CRUD.

Así que en lugar de

POST /v1/payments/authorization/<Authorization-Id>/capture POST /v1/payments/authorization/<Authorization-Id>/void POST /v1/payments/authorization/<Authorization-Id>/reauthorize

Hacer esto;

capture -> POST /v1/payments/authorization/<Authorization-Id> void -> DELETE /v1/payments/authorization/<Authorization-Id> reauthorize -> delete first then create again.

En REST, el verbo es el método HTTP. En su ejemplo, es POST pero también podría ser GET , PUT o DELETE .

El sustantivo es el recurso identificado por la URL. En su ejemplo, los "sustantivos" son /v1/payments/authorization/<Authorization-Id>/capture , etc.

Como puede ver, este no es realmente un nombre, ya que capture es un verbo: capturar una autorización de pago. Esto no es RESTful, ya que es un comando, un verbo, no una cosa, un sustantivo.

Una mejor manera sería modelar estos comandos como cosas /v1/payments/authorization/<Authorization-Id>/capturecommand . Este comando sería una cosa, un sustantivo. Podría haber estado, por ejemplo, si tuvo éxito, cuál fue el resultado, etc.

Hay una gran cantidad de código que dice ser RESTful y no lo es.