Est-il préférable de placer un REST API sur un sous-domaine ou dans un sous-dossier?
Nous avons une application Web hébergée avec l'URL http://example.com. Nous souhaitons maintenant étendre une partie de cette application en tant que service reposant et nous débattons du meilleur modèle d’URL. J'ai cherché mais je n'ai trouvé aucune indication concrète.
Devrions-nous avoir le modèle d'URL http://api.example.com ou http://exaple.com/api/v1?
Existe-t-il des directives standard pour cela?
Cela dépend de vos besoins.
Si vous utilisez http://api.example.com , votre API devient un sous-domaine. Fondamentalement, ce modèle d'URL est utile si votre service REST doit être utilisé par plusieurs clients, mais si un seul client est connecté à votre API, le modèle http://example.com/api/ v1 est bon. Toutefois, si vous souhaitez ajouter davantage d’API avec plus de clients connectés, il est préférable d’utiliser http://example.com/api/v1 . Par exemple, considérons ce qui suit.
http://example.com/reportapi/apioperation?parameters
http://example.com/paymentapi/apioperation?parameters
http://example.com/searchapi/apioperation?parameters
Enfin, Paypal utilise le modèle http://example.com/api/v1 .
Je pense que vous devriez envisager d’utiliser ni http://api.example.com ni http://example.com/api/v1.
Au lieu de cela, je suggérerais d'utiliser http://example.com/api et la négociation de contenu pour la gestion des versions.
Voici mes pensées pourquoi:
Utilisation d'un sous-domaine:
Conformément à la spécification de schéma d'URI , vous définissez l'API dans la partie autorité de l'URI, qui est utilisée pour définir votre hôte, plutôt que de définir une application ou une API sur votre hôte. Vous créez en réalité une adresse différente pour votre API, ce qui signifie que l'authentification pourrait ne pas fonctionner pour api.example.com comme pour exemple.com.
Cela peut être une raison valable pour concevoir une nouvelle instance pour les périphériques mobiles, par exemple. mobile.example.com, mais je considérerais cela plus comme une décision infrastructurelle que fonctionnelle.
Utilisation d'un chemin non versionné sur le domaine principal:
Il y a deux bits d'information ici: le premier indique qu'il existe une ressource API et le second le numéro de version de cette ressource API (v1).
Il n'y a rien de mal à utiliser /api/ pour faire la distinction entre l'API et, par exemple, votre affichage Web pouvant s'exécuter sous /web/. Cela peut être considéré comme une pratique exemplaire courante.
Je ne sais pas si vous aviez l'intention de le faire, mais votre question comprend une question sur la façon de résoudre le versioning des API. Personnellement, je pense que les versions d'API ne devraient pas être utilisées à l'aide d'URL, car elles sont censées rester stables le plus longtemps possible. _ { Les URI cool ne changent pas! Au lieu de cela, envisagez d'utiliser les informations HTTP Content-Type pour la version de votre API. J'ai effectivement trouvé cette méthode utilisée dans documentation VMware . De plus, voici un article assez ancien, mais toujours utile, sur la gestion des versions de type de contenu par Peter Williams .
C'est un cas de compromis, sans meilleure solution.
Par exemple, si votre http://example.com/ fournit du contenu via une interface Web standard ainsi que via l'API, vous avez besoin de quelque chose comme http://api.example.com/api/<version>/<the usual resource pattern> Uniquement pour séparer l'accès aux applications basé sur un navigateur. de l'interaction de l'API. Est-ce que ça a du sens?
Exemple: api.rottentomatoes.com
Toutefois, même si votre domaine est dédié aux appels d'API, il est néanmoins judicieux d'utiliser le modèle ci-dessus et de réserver http://example.com/ pour d'autres moyens d'interagir avec votre application. Par exemple, vous voudrez peut-être http://example.com/mobile/ , etc.