Quel type MIME si JSON est renvoyé par un REST API?
Mon REST API renvoie JSON.
Je retourne actuellement text/plain en tant que type MIME, mais c'est drôle .. Devrais-je renvoyer application/x-javascript ou un autre type?
La deuxième question concerne le code d'état HTTP pour les conditions d'erreur . Si mon API REST renvoie un état d'erreur, je retourne au format JSON.
{ result: "fail", errorcode: 1024, errormesg: "That sucked. Try again!" }
Le code d'état HTTP doit-il rester à 200 OK?
La spécification JSON suggère application/json, ce qui semble être pris en charge par les registres IETF et IANA .
En ce qui concerne la deuxième question, je pense que si le traitement du message échoue d’une manière ou d’une autre, vous devez renvoyer une réponse d'erreur structurée et standard sous forme de message JSON. si, pour une raison quelconque, le message n’est pas remis au gestionnaire dorsal, vous devez envisager un code d’erreur HTTP.
Mise à jour 2014-06-27: le temps où les clients (navigateurs) travaillaient avec une réponse 200 est révolu et le conseil qui prévaut pour les API RESTful consiste à utiliser les codes de réponse HTTP appropriés pour la réponse et 2xx pour les réponses correctes ( Par exemple, 201 créé pour PUT; 204 aucun contenu pour DELETE) et 4xx et 5xx pour toutes les conditions d'erreur, y compris celles de l'API elle-même.
Le type MIME de JSON est
application/json
http://www.ietf.org/rfc/rfc4627.txt
http://www.iana.org/assignments/media-types/application/
Plus spécifiquement ici:
Je préfère répondre avec un statut d'erreur HTTP et une charge utile spécifique à l'application.
Non, vous ne devriez pas retourner 200 en cas d'erreur.
Vous pouvez répéter le code d'état ou inclure un code d'erreur plus détaillé dans la charge de la réponse.
Le Content-type correct à renvoyer est application/json, conformément à RFC 4627 , qui enregistre également le type MIME IANA (et en effet, il apparaît sur la page de l'IANA). Bien sûr, si vous deviez écrire un client, vous voudriez être plus libéral dans ce que vous acceptez, et accepter d'autres tels que text/json et text/x-json.
Maintenant, s'il y a une erreur, vous devriez pas renvoyer HTTP 200, c'est fondamentalement non-RESTful. Je sais que parfois, votre erreur ne correspond pas exactement, mais choisissez les erreurs 4XX (du client) ou 5XX (du serveur) les plus proches dans RFC 2616, Sections 10.4 - 10.5, et soyez plus précis dans le JSON.
Si "API REST" signifie que vous voulez suivre une architecture REST, le type de support à utiliser est déterminé par la fonctionnalité que vous souhaitez exposer via l'API REST. Voulez-vous pouvoir créer de nouveaux objets? Interroger une liste d'objets? Modifier un objet? Si tel est le cas, vnd.collection + json peut être un bon type de média à utiliser car il définit une interface liée à un lien hypertexte pour manipuler une collection d'objets json.
Remarque: une API RESTful peut utiliser le type de média application/json, mais ce type de média ne possède pas d'interface RESTful liée par un lien hypertexte. Il s'agirait donc d'un point final du changement d'état.
Il est également tout à fait acceptable de suivre une architecture API Web, où les appels HTTP RPC renvoient des objets application/json, et les autres appels HTTP RPC manipulent ces objets, et il n’existe aucune interface de lien hypertexte permettant d’utiliser et de parcourir les changements d’état. Mais ce n'est pas REST.
J'aime cette description de REST (du créateur de REST):
REST APIS doit être piloté par l'hypertexte
En d'autres termes, si le moteur de l'état de l'application (et donc de l'API) n'est pas conduit par hypertexte, il ne peut donc pas être RESTful et ne peut pas être une API REST. Période.
En outre, cet exemple d’application RESTful est le suivant: Application Spam-E REST de Lost Boys