2.1 Aperçu général
2.1.1 Adresse d’accès
| Environnement de test | |
|---|---|
| Environnement réel | https://api.racent.com/ |
2.1.2 Authentification par signature d’API
L’interface utilise un mécanisme d’authentification basé sur la signature d’API afin de garantir l’intégrité et la sécurité des requêtes. À chaque appel d’interface, les paramètres de signature doivent être inclus, et le serveur vérifie l’exactitude de la signature.
Paramètres publics
Les paramètres suivants doivent être inclus dans la Query String de chaque requête d’interface :
| Nom du paramètre | Type de paramètre | Description | Exemple de valeur |
|---|---|---|---|
| access_key | String | ID de compte, utilisé pour identifier l’identité de l’appelant | 1000000059 |
| signature_nonce | String | Nonce unique de signature, utilisé pour empêcher les attaques par rejeu, une valeur aléatoire différente doit être utilisée à chaque requête | 2206561-6450-430e-8b0a-26980754c0de |
| timestamp | String | Horodatage d’envoi de la requête (en secondes) | 1673418729 |
| signature_version | String | Version de l’algorithme de signature, fixée à 1.0 | 1.0 |
| signature_method | String | Algorithme de signature, fixé à md5 | md5 |
| signature | String | Valeur de signature de cette requête, calculée à partir des autres paramètres et de la clé secrète | 85ef54421c69edeb098c7b557c6c5cd5 |
Remarque :
access_keyetAccessSecret(clé secrète) peuvent être obtenus après connexion depuis Gestion des interfaces - Identifiants d’accès API.
signature_nonceIl est recommandé d’utiliser un UUID ou une chaîne suffisamment aléatoire pour garantir l’unicité de chaque requête.timestampLes requêtes dont l’écart avec l’heure du serveur dépasse une certaine plage (par exemple 5 minutes) seront rejetées. :::
Mécanisme de signature
Étape 1 : Construire la chaîne de requête normalisée
1. Tri des paramètres
Triez tous les paramètres publics (à l’exception de signature) et les paramètres personnalisés de l’interface par ordre lexicographique croissant des noms de paramètres.
2. Encodage des paramètres
Encodez les noms et les valeurs de chaque paramètre en UTF-8 et effectuez un encodage URL conforme aux règles RFC3986 :
- Caractères non encodés :
A-Z a-z 0-9 - _ . ~ - Les autres caractères (tels que
espace,/,?,=, etc.) doivent être encodés au format %XX, par exemple l’espace est encodé en%20
3. Concaténation des paramètres
- Utilisez = pour relier le nom et la valeur du paramètre encodés
- Utilisez & pour relier toutes les paires de paramètres, en conservant l’ordre lexicographique
La chaîne finale obtenue est appelée stringToSign.
Étape 2 : Construire la chaîne de signature et calculer la signature
Selon le type de requête, la méthode de calcul de la signature est la suivante :
GET 请求
signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ))
POST / PUT 请求（含 Body 参数）
signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ) + md5( jsonStringToBody ))
Remarque :
- HTTPMethod doit être en majuscules, comme GET, POST
- jsonStringToBody est la chaîne JSON brute du corps de la requête (les espaces et les sauts de ligne doivent être supprimés, et les champs doivent être triés)
- Le + dans la formule indique une concaténation de chaînes, il ne participe pas au calcul
Règles d’encodage des paramètres (RFC3986)
| Type de caractère | Méthode de traitement | Exemple |
|---|---|---|
A-Z, a-z, 0-9, -, _, ., ~ | Sans encodage | abc123 → abc123 |
| Espace | Encodé comme %20 | a b → a%20b |
Autres caractères ASCII | Encodé comme %XX (hexadécimal) | " → %22 |
Exemple de requête GET
Supposons que :
- access_key = "1000000059"
- AccessSecret = "19938c89c13ddf5da7636333a5aa4c0e"
- signature_nonce = "iobzx72w63"
- timestamp = "1755597512"
Étape 1 : Construire stringToSign
access_key=1000000059&signature_method=md5&signature_nonce=iobzx72w63&signature_version=1.0×tamp=1755597512
Étape 2 : Calculer la signature
temp = md5("GET" + stringToSign) // 结果为"9bc92e0f3e239dc628ebc416294422ba"
signature = md5(AccessSecret + temp) // 结果为"a33bdb81ea79eb4ebbac9da043309c00"
URL de requête final :
https://api.racent.com/api/v1/domain/tld?access_key=1000000059&signature_nonce=iobzx72w63×tamp=1755597512&signature_version=1.0&signature_method=md5&signature=a33bdb81ea79eb4ebbac9da043309c00
Exemple de requête POST (avec Body)
Supposons que le Body soit :
{"domain":"example.com"}
Son MD5 est : 640c69595341436be9b0d1516d3d37ac
Étape 1 : Construire la chaîne à signer
access_key=1000000059&signature_method=md5&signature_nonce=abjipo5ar5a&signature_version=1.0×tamp=1755598851
Étape 2 : Calculer la signature
temp = md5("POST" + stringToSign) // 结果为 "5aba63e4af1b7a4080eaf47d0fc56efe"
signature = md5(AccessSecret + temp + "640c69595341436be9b0d1516d3d37ac") // 结果为 "29487fd8ae5b828415d05b691caf015c"
URL de demande finale :
https://api.racent.com/v1/domain/query-domain?access_key=1000000059&signature_nonce=abjipo5ar5a×tamp=1755598851&signature_version=1.0&signature_method=md5&signature=29487fd8ae5b828415d05b691caf015c
2.1.3 Limitation du débit de l’interface
Règles de limitation par défaut, pour un même utilisateur accédant à une même interface, les limites sont les suivantes :
- 60 fois par minute
- 500 fois par heure
- 1000 fois par jour
2.1.4 Paramètres de réponse de l’interface
Description des paramètres
| Nom du paramètre | Type du paramètre | Description | Exemple de valeur |
|---|---|---|---|
| data | Object | Données métier. Si l’interface renvoie une erreur, la valeur est null | |
| code | Int | Code d’erreur, 0 en cas de succès, code d’erreur correspondant en cas d’échec | 0, 1000, 1001 |
| message | String | Message d’erreur, renvoie « Success » en cas de succès | over-rate-limit |
| errors | Object | Pour certaines erreurs, des explications plus détaillées sont fournies via ce champ | |
| request_id | String | ID de requête, principalement utilisé pour faciliter le diagnostic | 039ecdca-44d5-430f-8521-020f4953bcc5 |