API publique
L'API publique de redirection.io offre un moyen d'interagir avec les organisations, projets et règles de redirection.io.
Veuillez noter que l'API publique de redirection.io n'est disponible que dans les organisations qui contiennent au moins un projet utilisant un plan "Starter" ou "Pro".
Considérations générales
Emplacement et disponibilité de l'API
L'API publique de redirection.io est disponible à l'adresse https://api.redirection.io : cette page fournit des informations générales sur l'utilisation de l'API, les points d'accès disponibles, etc. Elle propose également une spécification OpenAPI que vous pouvez utiliser pour intégrer l'API à vos propres outils : https://api.redirection.io/docs.json.
Dans les sections ci-dessous, toutes les requêtes API doivent être envoyées à l'hôte api.redirection.io avec le schéma https.
Sécurité
L'utilisation de l'API redirection.io nécessite une clé API, qui peut être créée dans l'écran "Jetons API" de votre organisation dans le gestionnaire :
- Ouvrez le gestionnaire redirection.io avec un compte administrateur d'organisation
- Rendez-vous sur l'écran "Paramètres > Jetons API" de votre organisation
Prenez soin de stocker ce jeton dans un endroit sécurisé, car il donne un contrôle complet sur votre organisation redirection.io.
Une fois créé, un jeton API doit être utilisé dans l'en-tête Authorization avec le préfixe Bearer, comme ci-dessous (bien sûr, remplacez la chaîne HERE_GOES_THE_TOKEN par la valeur du jeton) :
Authorization: Bearer HERE_GOES_THE_TOKENLimites de débit
Les appels à l'API publique de redirection.io sont soumis à des limites de débit. Nous limitons généralement les requêtes exécutées avec un jeton API donné à 10 requêtes par minute.
De plus, le point d'accès de publication des règles est limité à 20 requêtes par jour. Si vous avez besoin d'une limite plus élevée, veuillez nous contacter pour discuter de vos besoins spécifiques.
Lorsqu'une requête est limitée en débit, nous répondons avec un code de statut 429 Too Many Requests, accompagné d'un en-tête de réponse Retry-After.
Notez également que certaines de vos requêtes peuvent échouer, car votre projet peut être dans un état qui ne permet pas certaines opérations. Par exemple, il n'est pas possible de créer de nouvelles règles ou de publier des règles pendant qu'une importation de règles est en cours dans le projet.
Chaque fois que ce cas se produit, vous recevrez un code de statut de réponse 409 indiquant le conflit d'opérations.
Pagination
Les réponses de l'API sont paginées. Chaque page contient 100 éléments. La traversée des collections Rules ou Drafts peut être effectuée en utilisant le paramètre de chaîne de requête searchAfterId :
curl \
-XGET https://api.redirection.io/rules?projectId=HERE_GOES_THE_PROJECT_ID&searchAfterId=LAST_ID_OF_PREVIOUS_PAGE \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"Les collections Rules et Drafts sont triées par l'id des règles, afin de maintenir un ordre de tri cohérent lors d'une modification massive de règles sur toutes les pages.
Points d'accès disponibles
Détails de l'organisation
L'API peut être utilisée pour récupérer des informations sur l'organisation à laquelle appartient le jeton API, avec le point d'accès /organization :
curl \
-XGET https://api.redirection.io/organization \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"En retour, vous obtiendrez des informations de base sur l'organisation et ses projets :
{
"id" : "859fb30e-5c02-11eb-b66c-fa163e4748ca",
"name" : "ACME agency",
"projects" : [
{
"id" : "060201ae-88ad-4043-bd02-4661be4fcbd0",
"metadata" : [],
"name" : "ACME project",
"plan" : "starter_1000",
"slug" : "acme-project"
}
],
"slug" : "acme-agency"
}
L'id d'un projet est utile pour lister ou créer les règles de ce projet - nous l'utiliserons dans les paragraphes suivants.
Lister les règles d'un projet
Afin d'obtenir la liste des règles actuellement publiées, utilisez le point d'accès /rules (bien sûr, remplacez PROJECT_ID par l'id du projet dont vous voulez récupérer les règles) :
curl \
-XGET "https://api.redirection.io/rules?projectId=PROJECT_ID" \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"La réponse contient une liste d'objets Rule :
[
{
"id": "20fdf49e-85db-461f-bde9-033974870329",
"trigger": {
"source": "/blog/some-source-url",
"methods": [],
"requestHeaders": [],
"responseStatusCodes": [],
"ipAddress": null,
"sampling": null
},
"actions": [
{
"location": "/blog/blog-post-new-url",
"statusCode": 302,
"type": "redirection"
}
],
"markers": [],
"variables": [],
"examples": [],
"priority": 10,
"description": "This rule redirects an article of the blog to its new URL",
"metadata": [],
"enabled": true,
"tags": [
"CMS",
"blog",
"created with the API"
]
}
]
Rechercher une règle basée sur son URL de déclenchement
Lorsque vous utilisez l'API publique redirection.io à des fins d'automatisation, par exemple à partir du code de votre site web pour créer une nouvelle règle lorsqu'une URL de produit change, vous pouvez vouloir vérifier qu'il n'existe pas déjà une règle pour cette URL. Pour ce faire, vous pouvez utiliser la recherche de règle (ou de brouillon) par URL de déclenchement. Cela vous permettra de savoir si une règle existe déjà pour cette URL, et si c'est le cas, de la modifier ou de la supprimer avant d'en créer une nouvelle.
Cette recherche peut être effectuée en utilisant le paramètre de chaîne de requête triggerUrl des points d'accès /rules (pour les règles publiées) et /drafts (pour les brouillons). Il est important de noter que cette recherche ne renverra que les règles (ou brouillons) dont l'URL source correspond exactement à l'URL fournie. Par exemple, si vous avez une règle avec l'URL source https://www.example.com/old-url, la recherche avec triggerUrl=https://www.example.com/old-url renverra cette règle, mais pas si vous recherchez avec triggerUrl=https://www.example.com/old-url/. Il est donc important de respecter la syntaxe de l'URL pour obtenir les résultats attendus.
Voici un exemple de recherche de règle par URL source :
curl \
-XGET "https://api.redirection.io/rules?projectId=PROJECT_ID&triggerUrl=URL_TO_SEARCH" \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"Dans cet exemple, remplacez /TRIGGER_URL_TO_SEARCH par l'URL source que vous souhaitez rechercher. Si une règle existe pour cette URL, elle sera renvoyée dans la réponse. Sinon, vous obtiendrez une liste vide.
Créer une règle de redirection simple
L'API de redirection.io n'est pas destinée à remplacer entièrement le gestionnaire, mais constitue un moyen pratique de créer des règles par programme. Cependant, traiter avec notre API complète peut être un peu complexe si vous avez des exigences simples.
C'est la raison pour laquelle nous proposons le point d'accès /redirections, qui est un raccourci pour créer des règles de redirection simples, définies comme la combinaison de :
- une URL source (absolue ou relative) sans marqueur
- un code de statut de redirection
- un emplacement cible (absolu ou relatif)
Par exemple, imaginez que vous venez de changer le titre d'un article de blog dans votre CMS. Il est probable que l'URL de l'article ait également changé, et vous pourriez vouloir créer automatiquement une règle de redirection de l'ancienne URL vers la nouvelle. Le point d'accès /redirections permet une telle création rapide de règle :
curl \
-XPOST https://api.redirection.io/redirections \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
"project": "/projects/PROJECT_ID",
"source": "/blog/some-source-url",
"target": "/blog/blog-post-new-url",
"statusCode": 302
}
EOFSi la charge utile soumise est valide, la réponse contiendra un objet Draft, qui décrit la nouvelle règle brouillon créée :
[
{
"id" : "0184097b-82dd-3cf6-1199-e39f730f2cce",
"status" : "add",
"rule" : {
"id" : "12b93f68-32b8-4efb-9484-241c8421bb8a",
"trigger" : {
"ipAddress" : null,
"methods" : [],
"requestHeaders" : [],
"responseStatusCodes" : [],
"sampling" : null,
"source" : "/blog/some-source-url"
},
"actions" : [
{
"location" : "/blog/blog-post-new-url",
"statusCode" : 302,
"type" : "redirection"
}
],
"description" : null,
"enabled" : true,
"examples" : [],
"markers" : [],
"metadata" : [],
"priority" : 0,
"tags" : [],
"variables" : []
}
}
]
Comme vous pouvez le voir, le Draft résultant contient la description d'une règle redirection.io complète, ainsi que le statut du brouillon (qui peut être add, update ou delete, selon l'opération effectuée).
Si vous avez besoin de configurer des déclencheurs ou des actions plus spécialisés, utilisez plutôt le point d'accès /rules (décrit dans le paragraphe suivant) pour un contrôle complet des règles. En aparté, la charge utile de la requête pour le point d'accès /redirections prend en charge certaines métadonnées facultatives :
enabled: la règle doit-elle être activée ou non ?description: un message de description doit-il être attaché à la règle ?priority: quelle valeur de priorité doit être associée à la règle ?tags: un tableau facultatif de chaînes de caractères à associer aux règles, ce qui peut être utile lors de la recherche d'une règle spécifique
Voici un exemple de charge utile complète :
{
"project": "/projects/PROJECT_ID",
"source": "/blog/some-source-url",
"target": "/blog/blog-post-new-url",
"statusCode": 302,
"enabled": false,
"description": "This rule redirects an article of the blog to its new URL",
"priority": 10,
"tags": ["CMS", "blog", "created with the API"]
}Une fois créée, la règle associée apparaît comme un "brouillon" dans la liste des règles du gestionnaire :
Veuillez noter que, lorsqu'une règle est créée, elle n'est pas appliquée à votre site web tant qu'elle n'est pas publiée. De plus, elle n'est pas listée par le point d'accès /rules, car celui-ci ne liste que les règles publiées. Cependant, vous pouvez récupérer cette règle en utilisant le point d'accès /drafts :
curl \
-XGET "https://api.redirection.io/drafts?projectId=PROJECT_ID" \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"Ceci renvoie la liste des modifications de brouillon qui seront appliquées lorsque les règles seront publiées :
[
{
"id" : "01840988-96f5-f1df-9841-69af039d6aa6",
"rule" : {
"actions" : [
{
"location" : "/blog/blog-post-new-url",
"statusCode" : 302,
"type" : "redirection"
}
],
"description" : "This rule redirects an article of the blog to its new URL",
"enabled" : false,
"examples" : [],
"id" : "20fdf49e-85db-461f-bde9-033974870329",
"markers" : [],
"metadata" : [],
"priority" : 10,
"tags" : [
"CMS",
"blog",
"created with the API"
],
"trigger" : {
"ipAddress" : null,
"methods" : [],
"requestHeaders" : [],
"responseStatusCodes" : [],
"sampling" : null,
"source" : "/blog/some-source-url"
},
"variables" : []
},
"status" : "add"
}
]
Créer des règles de trafic plus complexes
L'API publique de redirection.io offre également un contrôle total sur les déclencheurs et les actions. Dans de nombreux scénarios, vous souhaiterez créer des règles complexes par programme. Tous les déclencheurs et actions de redirection.io sont disponibles dans l'API publique, tels que décrits dans le modèle Rule.
Créer des marqueurs à l'aide de l'API
Voici un exemple simple de création d'une variable de marqueur dans une règle :
curl \
-XPOST https://api.redirection.io/rules \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
"project": "/projects/PROJECT_ID",
"trigger": {
"source": "/animals/@everything"
},
"actions": [
{
"type": "redirection",
"location": "https://example.com/pets/@everything",
"statusCode": 307
}
],
"markers": [
{
"name": "everything",
"type": "anything"
}
],
"variables": [
{
"type": "marker",
"name": "everything",
"marker": "everything"
}
],
"examples": [
{
"mustMatch": true,
"url": "https://example.com/animals/fish"
},
{
"mustMatch": false,
"url": "https://example.com/not-matching/fish"
}
],
"description": "A redirect rule with a marker",
"enabled": true,
"tags": [
"api created rule"
]
}
EOFCeci entraînera la création de la règle brouillon suivante :
Exemple complet
Voici un exemple d'appel de création de règle (assez complet) :
curl \
-XPOST https://api.redirection.io/rules \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
"project": "/projects/PROJECT_ID",
"trigger": {
"source": "/animals/@animalName",
"methods": [
"GET",
"POST"
],
"requestHeaders": [
{
"name": "User-Agent",
"operator": "contains",
"value": "bot"
}
],
"responseStatusCodes": [
418
],
"ipAddress": {
"type": "inRange",
"start": "1.2.3.4",
"end": "1.2.3.255"
},
"sampling": 23
},
"actions": [
{
"type": "customHtml",
"value": "<!-- Hello -->",
"location": "headStart"
},
{
"type": "redirection",
"location": "https://example.com/pets/@animal",
"statusCode": 307
},
{
"type": "header",
"name": "X-Redirectionio-Method",
"value": "The method for this request was: @httpMethod",
"mode": "override"
}
],
"markers": [
{
"name": "animalName",
"type": "enum",
"values": [
"dog",
"cat",
"fish"
],
"transformers": [
{
"type": "uppercase"
}
]
}
],
"variables": [
{
"type": "marker",
"name": "animal",
"marker": "animalName"
},
{
"type": "requestMethod",
"name": "httpMethod",
"transformers": [
{
"type": "lowercase"
}
]
}
],
"examples": [
{
"mustMatch": true,
"url": "https://example.com/animals/fish",
"method": "GET",
"responseStatusCode": 418,
"headers": [
{
"name": "User-Agent",
"value": "example-bot/1.0"
}
],
"ipAddress": "1.2.3.10"
},
{
"mustMatch": true,
"url": "https://example.com/animals/dog",
"method": "POST",
"responseStatusCode": 418,
"headers": [
{
"name": "User-Agent",
"value": "generic-bot"
}
],
"ipAddress": "1.2.3.118"
},
{
"mustMatch": false,
"url": "https://example.com/animals/cat",
"method": "DELETE"
}
],
"description": "Some quite complete rule example",
"enabled": true,
"tags": [
"animals",
"api created rule"
]
}
EOFCeci entraînera la création de la règle brouillon suivante :
Publier les règles
Une fois qu'une règle est créée, modifiée ou supprimée à l'aide de l'API publique, elle est listée comme un changement "brouillon" dans votre ensemble de règles. Cela signifie que, à moins que vous ne publiiez les règles :
- la règle n'est pas appliquée sur votre site web de production ;
- les changements ne sont pas listés dans le point d'accès
/rules; - les changements n'apparaissent que dans le point d'accès
/drafts.
Vous pouvez publier les règles en utilisant l'interface graphique, ou en utilisant l'API :
curl \
-XPOST https://api.redirection.io/projects/PROJECT_ID/publish \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"Cet appel déclenche la publication de toutes les modifications effectuées dans l'ensemble de règles, qui seront rapidement disponibles sur votre site web en direct !
Utilisation et conseils
L'API publique de redirection.io est assez simple à utiliser et s'avère utile pour intégrer la gestion des redirections dans votre système de gestion de contenu. Cependant, il y a quelques astuces à connaître pour éviter les pièges courants.
Création automatique de règles
Vous pourriez vouloir créer une nouvelle règle de redirection lorsque l'URL d'une page ou d'un produit change sur votre site web. Les sites de commerce électronique, en particulier dans le secteur de la mode, peuvent vouloir déplacer une page de produit de la collection actuelle vers une section d'archive, dans une autre catégorie du site ou parfois même sous un autre sous-domaine.
Ce faisant, vous devez veiller à ne pas perturber votre plan de redirection en ajoutant de nouvelles règles qui créeraient des chaînes de redirection ou, pire, des boucles.
Éviter les chaînes de redirection
Le point d'accès /redirections permet de créer de nouvelles règles redirection.io.
Par exemple, imaginez que le produit situé à https://example.com/current/1234-some-product doive être déplacé vers https://example.com/archive/1234-some-product. Dans votre CMS, vous changeriez l'URL du produit, et vous utiliseriez l'API redirection.io pour créer une nouvelle règle pour la redirection associée.
Puis, après quelques mois, lorsque l'URL du produit change à nouveau, par exemple vers https://example.com/retired-products/1234-some-product, vous devrez créer une nouvelle règle, pour rediriger de /archive/1234-some-product vers /retired-products/1234-some-product. Ce faisant, il y aura une chaîne de redirections : une requête vers /current/1234-some-product sera d'abord redirigée vers /archive/1234-some-product qui sera elle-même redirigée vers /retired-products/1234-some-product. Bien que les chaînes de redirection ne soient pas un problème majeur, elles peuvent consommer du budget de crawl, ce qui est toujours préférable d'éviter.
Par conséquent, vous pourriez modifier la première règle de redirection pour rediriger directement le chemin /current/1234-some-product vers /retired-products/1234-some-product. À condition d'avoir stocké l'ID de la règle qui a été donné en réponse au premier appel de création de règle, vous pouvez modifier cette règle directement en utilisant le point d'accès updateRule :
curl \
-XPUT https://api.redirection.io/rules/RULE_ID \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
"project": "/projects/PROJECT_ID",
"trigger": {
...
},
"actions": [
...
],
"markers": [
...
],
"variables": [
...
],
"examples": [
...
],
"description": "Some new description",
"enabled": true,
"tags": [
...
]
}
EOFPar conséquent, il peut être judicieux de stocker, dans votre CMS ou votre plateforme e-commerce, l'identifiant de la règle associé à une page ou un produit donné, afin de pouvoir le récupérer par la suite et soit le supprimer (si la redirection n'est plus nécessaire) soit le modifier (si la redirection doit être changée).
Éviter les boucles de redirection
Notre page de documentation sur la base de connaissances "Qu'est-ce qu'une redirection d'URL ? explique déjà en détail pourquoi vous devriez éviter les boucles de redirection."
Lors de la création de nouvelles règles via le gestionnaire redirection.io, des exemples sont attachés à vos règles, et l'étape "Impact" permet de détecter les problèmes potentiels avec la règle nouvellement créée.
Lors de l'utilisation de l'API publique, une telle vérification d'impact n'est pas possible, car il n'y a pas d'interactivité utilisateur. En d'autres termes, redirection.io stocke aveuglément les nouvelles règles créées par API, et s'appuie entièrement sur vos propres vérifications pour supposer leur validité.
Éviter les boucles de redirection peut être un défi dans ce contexte - une bonne approche peut être de s'assurer qu'il n'y a pas de règle qui redirige la cible de la règle que vous êtes sur le point de créer. En d'autres termes, avec le schéma ci-dessus, si vous êtes sur le point de créer la redirection /d --> /a, vérifiez d'abord qu'il n'y a pas de règle utilisant /a comme URL source.
Si vous créez des règles automatiques associées à un article ou un produit spécifique de votre CMS ou site web e-commerce, il est judicieux de stocker dans votre backend l'identifiant des règles redirection.io qui ont été créées pour ce produit.
Reprenons l'exemple ci-dessus d'un produit initialement situé à https://example.com/current/1234-some-product qui doit être déplacé vers https://example.com/archive/1234-some-product (1). Dans votre CMS, vous changeriez l'URL du produit, et vous utiliseriez l'API redirection.io pour créer une nouvelle règle pour la redirection associée. Ensuite, après quelques mois, l'URL du produit doit être changée à nouveau vers l'URL initiale, https://example.com/current/1234-some-product (2).
Pendant (1), vous créeriez une première règle de redirection. Avant de créer une autre règle pendant (2), vous devez bien sûr supprimer la règle créée pendant (1). En d'autres termes, lorsque le produit est déplacé dans votre CMS, vous devez effectuer plusieurs appels API :
- si une règle est déjà associée à ce produit, supprimez la règle en utilisant le point d'accès deleteRule
- ensuite, créez la nouvelle règle
- publiez les changements