Wie sieht eine REST-konforme API-Adresse beim Abrufen von Daten für einen bestimmten Suchbegriff aus?

Question

Was ist der sauberste Weg, eine RESTful-API zu entwickeln, an die Sie Suchbegriffe weiterleiten möchten?

Zum Beispiel habe ich einen Endpunkt namens "Jobs" und ein Job könnte entweder ein eingehender oder ein ausgehender Job sein. Ich möchte alle ausgehenden Jobs auflisten.

Normalerweise würde ich die ID an die Web-URL wie /api/jobs/12 für einen bestimmten Datensatz übergeben. Wie würde die URL aussehen, um alle Jobs für einen bestimmten Typ anzuzeigen?

Wäre es etwas wie /api/jobs/?direction=inbound? Sehen so normale RESTful-Adressen aus?

Ich verwende Angular $resource und nicht sicher, wie Sie dies einrichten. Zuvor etwas wie dieses ich mich zu geben, verwenden, um eine bestimmte Entität zurück:

return $resource(settings.apiUrl + 'jobs/:id', {id: '@id'}, { 
    'update' : { method: 'PUT' }, 
    'query': {method: 'GET', isArray: false } 
    }); 

Answer 1

Zu allererst sollte RESTful Prinzipien nicht das Ende-all-sein-all, wenn Sie Ihre API-Struktur-Design. Konzentrieren Sie sich stattdessen darauf, anderen Entwicklern den Konsum zu erleichtern, und binden Sie sich nicht zu sehr in RESTfulness. Die Erfüllung aller REST-Prinzipien ist sehr schwierig und die meisten APIs nicht.

Das heißt, wenn Ihre Arbeit Objekte eine direction Eigenschaft haben, diese URL völlig in Ordnung ist (und meine persönlich bevorzugte Methode), und eine Menge von APIs tun es auf diese Weise:

GET /api/jobs?direction=inbound 

Wenn Sie müssen Rückkehr Jobs basierend auf etwas anderes als eine Eigenschaft des Auftragsobjekts, für Arbeitsplätze Beispiel abgebrochen, dies auch sehr verbreitet ist:

GET /api/jobs/cancelled 

Obwohl in diesem Fall würde ich es vorziehen, eine status Eigenschaft zum Job-Objekt hinzuzufügen und Verwenden Sie stattdessen:

GET /api/jobs?status=cancelled