Construisez votre propre surface de contrôle

Le contrat de version un proposé sépare les ressources du catalogue des ressources du compte. Les emplacements et les forfaits prennent en charge la configuration. Les services représentent les configurations acceptées et l'état d'exécution. La facturation contient les factures et l'état des paiements. Les tickets prennent en charge une conversation de support traçable. Le site web met en œuvre ses propres formulaires et espace de travail ; les exemples ci-dessous sont un contrat de conception, et non des routes vers un API public.

Le modèle d'authentification préparé utilise un jeton Bearer dans l'en-tête Authorization. Les portées de catalogue ou de service en lecture seule ne devraient pas pouvoir créer, reconstruire ou annuler un service. Les portées d'écriture nécessitent une décision distincte et un chemin de révocation. Conservez les identifiants dans un environnement serveur privé et n'intégrez jamais un jeton secret dans une page ou un bundle de navigateur.

GET /v1/services
Authorization: Bearer <private-token>
Accept: application/json

# Proposed scope: services:read

Utilisez un identifiant stable pour chaque ressource et un identifiant de requête pour le support. Les appels mutants doivent prendre une clé d'idempotence afin qu'une nouvelle tentative puisse être réconciliée au lieu de créer une autre commande.

POST /v1/services
Idempotency-Key: <one-key-per-request>

{
  "plan_id": "umbra-1",
  "location": "iceland",
  "billing_cycle": "monthly",
  "image": "Ubuntu"
}

Les limites de débit proposées au niveau du compte sont de 60 lectures par minute et de 20 écritures par minute, avec une tolérance de rafale du double de ces valeurs. Une requête rejetée renvoie HTTP 429 avec Retry-After ; l'automatisation doit attendre comme indiqué et appliquer un backoff. Les erreurs doivent inclure un code stable, un message lisible par l'homme et un request_id, avec les détails sensibles supprimés.

{
  "error": {
    "code": "unsupported_location",
    "message": "This plan is not listed in that region.",
    "request_id": "req_example"
  }
}

Le modèle de webhook préparé couvre le paiement des factures, la disponibilité du service, la suspension et les mises à jour des tickets. La livraison doit comporter un ID d'événement et un horodatage, avec une signature HMAC-SHA256 vérifiée sur le corps de la requête d'origine à l'aide d'un secret de signature privé. Rejetez les signatures obsolètes ou invalides, dédupliquez les ID d'événement et n'accusez réception qu'après acceptation durable de l'événement. Les consommateurs doivent tolérer une livraison dans le désordre et répétée.

Le chemin API proposé inclut sa version majeure. Les modifications additives devraient préserver les clients existants ; les modifications incompatibles nécessitent une nouvelle version et un préavis de retrait de six mois pour l'ancienne. La disponibilité, les SDK et un hôte de production API ne doivent être publiés qu'après examen de l'intégration et de la sécurité.

L'application de compte dispose de demandes de paiement à adresse fixe et de devis serveur USD expirants. L'observation des transactions est une intégration de confiance côté serveur uniquement ; il n'existe aucun point de terminaison public de confirmation, aucun moniteur de blockchain connecté ni worker de provisionnement. L'interrogation par le navigateur lit l'état de paiement existant du client connecté et ne peut pas attester d'une transaction. L'API publique illustrative et le contrat de webhook ci-dessus restent des travaux de conception futurs.

• Protéger la logique de débit et d’observation sur le serveur.
• Associez les destinations de réception réutilisées à une transaction vérifiée et à une référence de commande explicite.
• Gardez le payé et le provisionné séparés ; une transaction vérifiée ne doit pas créer de matériel fictif.