Πώς να γράψετε προδιαγραφές διασύνδεσης που ένας προμηθευτής δεν μπορεί να παρερμηνεύσει

Βασικά συμπεράσματα

• Οι περισσότερες διαφωνίες στις διασυνδέσεις οφείλονται σε ασάφεια της τεκμηρίωσης, όχι σε τεχνικές διαφορές — το προσχέδιο του IETF για τα κλειδιά ιδιοδυναμίας υπάρχει ακριβώς επειδή η συμπεριφορά επανάληψης ήταν το πιο αμφισβητούμενο σημείο μεταξύ προμηθευτών API και ομάδων διασύνδεσης (IETF httpapi-idempotency-key-header).
• Καθορίστε τη σημασιολογία των σφαλμάτων στη μορφή Problem Details του RFC 9457. Είναι το τρέχον πρότυπο του IETF για σώματα σφαλμάτων αναγνώσιμα από μηχανές και αντικαθιστά το παλαιότερο RFC 7807 (RFC 9457).
• Δηλώστε ρητά το όριο επαναλήψεων, την καμπύλη αναμονής και τη στρατηγική τυχαίας διακύμανσης. Η δημοσιευμένη οδηγία της AWS είναι «δυαδική εκθετική αύξηση αναμονής με τυχαία διακύμανση» — χρησιμοποιήστε αυτή τη διατύπωση στις προδιαγραφές ώστε ο προμηθευτής να μην μπορεί να την αμφισβητήσει αργότερα (AWS Architecture Blog).
• Χρησιμοποιήστε το σχήμα OpenAPI 3.1 ως μοναδική αναφορά για το συμβόλαιο δεδομένων, αντί για περιγραφικό κείμενο. Στο κείμενο γεννιούνται οι παρερμηνείες (OpenAPI Specification 3.1).
• Εντάξτε την παρατηρησιμότητα στο συμβόλαιο: όνομα κεφαλίδας συσχέτισης, χρόνος διατήρησης καταγραφών και διεύθυνση του πίνακα παρακολούθησης που θα σας κοινοποιήσει ο προμηθευτής κατά τα περιστατικά. Αν δεν περιλαμβάνεται στις προδιαγραφές, δεν θα το έχετε στις 2 το πρωί.

Συνοπτικά

Ένα χρήσιμο πρότυπο προδιαγραφών διασύνδεσης — που ένας προμηθευτής δεν μπορεί εύλογα να παρερμηνεύσει — έχει λίγα συγκεκριμένα χαρακτηριστικά. Ορίζει τα δεδομένα αιτημάτων και αποκρίσεων ως σχήματα OpenAPI, όχι ως παραγράφους. Ονομάζει μια κεφαλίδα κλειδιού ιδιοδυναμίας και δηλώνει, σε μία πρόταση, τι πρέπει να κάνει ο διακομιστής όταν εντοπίσει διπλότυπο. Καθορίζει το όριο επαναλήψεων, την καμπύλη αναμονής και τη στρατηγική τυχαίας διακύμανσης με αριθμούς που μπορεί να υλοποιήσει ο προμηθευτής. Τα σώματα σφαλμάτων ακολουθούν το Problem Details του RFC 9457. Η αυθεντικοποίηση, τα όρια ρυθμού και η υπογραφή webhook έχουν το καθένα ξεχωριστή, χρονολογημένη υποενότητα με αναλυτικό παράδειγμα. Και, κυρίως, οι προδιαγραφές ορίζουν ονομαστικά έναν υπεύθυνο σε κάθε πλευρά και μία έγκυρη διεύθυνση αναφοράς — συνήθως ένα αποθετήριο Git με εκδόσεις του openapi.yaml — ώστε το «τι λένε οι προδιαγραφές» να μην αποτελεί ποτέ ζήτημα γνώμης. Το υπόλοιπο άρθρο είναι ένα πρότυπο ανά ενότητα που μπορείτε να προσαρμόσετε, μαζί με τις ερωτήσεις που υποχρεώνουν τον προμηθευτή να πάρει αποφάσεις πριν γραφτεί κώδικας.

Γιατί το σφάλμα είναι η ασάφεια

Την πρώτη φορά που ένα έργο διασύνδεσης B2B πηγαίνει άσχημα, η διατύπωση της ανασκόπησης είναι σχεδόν πάντα λανθασμένη. Οι μηχανικοί λένε «το API του προμηθευτή είχε σφάλματα». Οι προμηθευτές λένε «η ομάδα διασύνδεσης χρησιμοποίησε λάθος το API». Συνήθως και οι δύο περιγράφουν το ίδιο πράγμα: προδιαγραφές που δεν δεσμεύονταν για συγκεκριμένη συμπεριφορά και δύο ομάδες που κάλυψαν το κενό με διαφορετικές προεπιλογές.

Η ιδιοδυναμία είναι το χαρακτηριστικό παράδειγμα. Το IETF έχει ένα προσχέδιο προτύπου γι' αυτήν (Idempotency-Key) και η ίδια η περιγραφή του προβλήματος είναι σαφής: «Η κατανεμημένη και αποκεντρωμένη φύση διαφόρων συστημάτων δυσκολεύει τον εντοπισμό διπλοτύπων και τη συμφωνία αποτυχημένων συναλλαγών», ενώ τα κλειδιά ιδιοδυναμίας «επιτρέπουν στους παρόχους API να εξασφαλίζουν σημασιολογία ακριβώς μίας εκτέλεσης για τα αιτήματα των πελατών» (IETF httpapi-idempotency-key-header). Το ότι χρειάστηκε ένα προσχέδιο RFC για να διευθετηθεί αυτό δείχνει πόσα χρήματα έχουν χαθεί από την ασάφεια των προδιαγραφών γύρω από τις επαναλήψεις.

Οι προδιαγραφές δεν είναι κατάλογος επιθυμιών. Είναι το έγγραφο που αναζητάτε στις 2 το πρωί, όταν η παραγωγή χρεώνει διπλά τους πελάτες, και πρέπει να δείξετε μία παράγραφο που λέει «ο διακομιστής δεν πρέπει να παράγει περισσότερες από μία παρενέργειες ανά κλειδί ιδιοδυναμίας, ακόμη και με επαναλήψεις, για τουλάχιστον 24 ώρες». Αν αυτή η παράγραφος λείπει, έχετε μια ελπίδα αντί για προδιαγραφές.

Το πρότυπο, ενότητα προς ενότητα

Ακολουθεί η δομή που χρησιμοποιώ στα έργα. Έχει σαφή άποψη και σκόπιμα αναγκάζει τις ομάδες προϊόντος των προμηθευτών να απαντούν σε ερωτήματα που θα προτιμούσαν να αφήσουν ασαφή. Στόχος δεν είναι η γραφειοκρατική πληρότητα, αλλά η λήψη αποφάσεων. Κάθε ενότητα τελειώνει με την ερώτηση που επιστρέφω όταν λείπει η απάντηση του προμηθευτή.

1. Αντικείμενο, ευθύνη και έγκυρη αναφορά

Δηλώστε ποια διασύνδεση αφορά το έγγραφο, ποιες επιχειρησιακές ροές υποστηρίζει και τι εξαιρείται ρητά από το αντικείμενό της. Ορίστε ονομαστικά έναν κύριο τεχνικό υπεύθυνο σε κάθε πλευρά και μία διεύθυνση σε αποθετήριο Git όπου βρίσκεται το κανονικό openapi.yaml. Προσδιορίστε την έκδοση των προδιαγραφών με ημερομηνία και ετικέτα Git — ποτέ με την ονομασία «v1 τελικό».

Ρωτήστε: Πού θα βρίσκεται το σχήμα που είναι αναγνώσιμο από μηχανές, ποιος θα μπορεί να το τροποποιεί και πώς θα γνωστοποιούνται οι αλλαγές; Αν η απάντηση του προμηθευτή είναι «θα σας στέλνουμε ένα PDF όταν υπάρχουν ενημερώσεις», υπάρχει πρόβλημα διαδικασίας και πρέπει να το συνυπολογίσετε στο κόστος.

2. Μεταφορά, αυθεντικοποίηση και διαχωρισμός πελατών

Καθορίστε το πρωτόκολλο (REST/HTTPS, gRPC, διαμεσολαβητής μηνυμάτων), το σχήμα αυθεντικοποίησης (OAuth 2.1 client credentials, mTLS, υπογραφή αιτήματος με HMAC) και τον τρόπο με τον οποίο κάθε αίτημα δηλώνει τον πελάτη στον οποίο ανήκει. Το OAuth 2.1 αποτελεί πλέον το ενοποιημένο προφίλ του IETF και την κατάλληλη προεπιλογή για νέες διασυνδέσεις μεταξύ διακομιστών (draft-ietf-oauth-v2-1). Για webhook με υπογραφή HMAC, ονομάστε τον αλγόριθμο, τους κανόνες κανονικοποίησης και την κεφαλίδα.

Ρωτήστε: Πόσο συχνά ανανεώνονται τα διαπιστευτήρια και ποια είναι η τεκμηριωμένη διαδικασία όταν υπάρχει υποψία παραβίασης ενός μυστικού; Αν δεν υπάρχει τεκμηριωμένη διαδικασία, γράψτε την και προσθέστε την ως παράρτημα.

3. Συμβόλαιο δεδομένων: OpenAPI αντί για περιγραφικό κείμενο

Συνδέστε τα δεδομένα αιτημάτων και αποκρίσεων με ένα σχήμα OpenAPI 3.1 (OpenAPI Specification 3.1). Η έκδοση 3.1 είναι πλήρως συμβατή με το JSON Schema 2020-12, κάτι σημαντικό επειδή καταργεί τις παλαιότερες ασυμβατότητες που ταλαιπωρούσαν ομάδες με κοινούς μηχανισμούς επικύρωσης σε παραγωγό και καταναλωτή.

Το περιεχόμενο αυτής της ενότητας είναι μία πρόταση: «Όλα τα δεδομένα αιτημάτων και αποκρίσεων ορίζονται στο openapi.yaml στην παραπάνω έγκυρη διεύθυνση αναφοράς. Το παρόν έγγραφο δεν επαναλαμβάνει περιγραφές σε επίπεδο πεδίου. Όταν το κείμενο και το σχήμα διαφωνούν, υπερισχύει το σχήμα.» Αυτή η πρόταση από μόνη της επιλύει μια ολόκληρη κατηγορία διαφωνιών.

Ρωτήστε: Ποια πεδία επιτρέπουν κενή τιμή, ποια είναι προαιρετικά και πώς χειρίζεται ο διακομιστής τα άγνωστα πεδία — τα απορρίπτει, τα αγνοεί ή τα επιστρέφει; Ζητήστε από τον προμηθευτή να δεσμευτεί σε μία επιλογή.

4. Ιδιοδυναμία

Αυτή είναι η ενότητα που λείπει συχνότερα. Η προσέγγιση της Stripe είναι το ντε φάκτο πρότυπο του κλάδου και αξίζει να την υιοθετήσετε αυτούσια: ο πελάτης στέλνει μια κεφαλίδα Idempotency-Key με UUID ανά λογική πράξη· ο διακομιστής αποθηκεύει το αποτύπωμα του αιτήματος και την απόκριση για τουλάχιστον 24 ώρες· σε διπλότυπο κλειδί με ίδιο αποτύπωμα, επιστρέφει την αποθηκευμένη απόκριση· σε διπλότυπο κλειδί με διαφορετικό αποτύπωμα, επιστρέφει συγκεκριμένο σφάλμα (Stripe API Reference — Idempotent Requests).

Καθορίστε με ακρίβεια:

• Το όνομα της κεφαλίδας (με προεπιλογή Idempotency-Key, σύμφωνα με το προσχέδιο του IETF).
• Το ελάχιστο διάστημα διατήρησης (οι 24 ώρες είναι η προεπιλογή κατά το πρότυπο της Stripe· οι 7 ημέρες είναι ασφαλέστερες για μαζικές διασυνδέσεις).
• Τη συμπεριφορά σε διαφορετικό αποτύπωμα (επιστροφή 409 με σώμα problem+json).
• Αν το κλειδί είναι καθολικό, περιορίζεται στο διακριτικό API ή περιορίζεται στον πελάτη.

Ρωτήστε: Τα αιτήματα GET και DELETE αντιμετωπίζονται ως εγγενώς ιδιοδύναμα σύμφωνα με το RFC 9110 ή δέχονται επίσης την κεφαλίδα ιδιοδυναμίας; Το RFC 9110 ορίζει τα GET, HEAD, PUT και DELETE ως ιδιοδύναμα εξ ορισμού (RFC 9110 §9.2.2), αλλά οι προμηθευτές διαφωνούν για το αν επιτρέπεται η κεφαλίδα σε αυτές τις μεθόδους. Πάρτε σαφή θέση.

5. Κανόνες επανάληψης, αναμονή και τυχαία διακύμανση

Δηλώστε με αριθμούς το όριο επαναλήψεων του πελάτη και τις προσδοκίες του διακομιστή. Η διατύπωση που χρησιμοποιώ προέρχεται σχεδόν αυτούσια από τη δημοσιευμένη αρχιτεκτονική καθοδήγηση της AWS: «υλοποιήστε αλγόριθμο εκθετικής αύξησης αναμονής με τυχαία διακύμανση», με μέγιστη καθυστέρηση, μέγιστο αριθμό προσπαθειών και σύσταση αποφυγής επαναλήψεων σε αποκρίσεις 4xx, εκτός από 408, 425 και 429 (AWS Architecture Blog).

Μια συγκεκριμένη ρήτρα για τις προδιαγραφές:

Οι πελάτες ΣΥΝΙΣΤΑΤΑΙ να επαναλαμβάνουν παροδικές αποτυχίες με εκθετική αύξηση αναμονής και πλήρη τυχαία διακύμανση, με βάση 200 ms και ανώτατο όριο 30 s, έως 6 προσπάθειες μέσα σε χρονικό περιθώριο 10 λεπτών. Οι επαναλήψεις ΠΡΕΠΕΙ να φέρουν το ίδιο Idempotency-Key με το αρχικό αίτημα. Οι πελάτες ΔΕΝ ΠΡΕΠΕΙ να επαναλαμβάνουν αποκρίσεις 4xx εκτός από 408 Request Timeout, 425 Too Early, 429 Too Many Requests και 5xx.

Η κεφαλίδα Retry-After είναι η δικλίδα του διακομιστή. Το RFC 9110 την ορίζει με ακρίβεια, μαζί με τις δύο έγκυρες μορφές τιμών της (διάστημα σε δευτερόλεπτα και ημερομηνία HTTP) (RFC 9110 §10.2.3). Δηλώστε ποια μορφή θα χρησιμοποιεί ο διακομιστής και απαιτήστε από τον πελάτη να τη σέβεται.

Ρωτήστε: Ποια είναι η τεκμηριωμένη απόκριση υπέρβασης ορίου ρυθμού — 429, ποιες κεφαλίδες περιλαμβάνει και τι αναμένει ο διακομιστής να κάνει ο πελάτης;

6. Ταξινόμηση σφαλμάτων

Τα σφάλματα είναι το σημείο που προδιαγράφεται λανθασμένα συχνότερα. Βασίστε τα στο RFC 9457 Problem Details for HTTP APIs, που είναι πλέον το πρότυπο του IETF (RFC 9457). Το RFC 9457 καταργεί το παλαιότερο RFC 7807 και αποσαφηνίζει ορισμένα πρακτικά ζητήματα, μεταξύ άλλων τον χειρισμό μελών επέκτασης.

Ένα σώμα problem+json έχει πέντε ονομασμένα μέλη: type (URI που προσδιορίζει την κατηγορία προβλήματος), title (σύντομη, ανθρωπίνως αναγνώσιμη σύνοψη), status (κωδικός κατάστασης HTTP), detail (ανθρωπίνως αναγνώσιμη εξήγηση για το συγκεκριμένο συμβάν) και instance (URI που προσδιορίζει το συγκεκριμένο συμβάν). Συνδέστε τα URI του type με έναν τεκμηριωμένο κατάλογο — αυτός ο κατάλογος είναι η πραγματική ταξινόμηση σφαλμάτων.

Η ελάχιστη χρήσιμη ταξινόμηση έχει περίπου δώδεκα καταχωρίσεις: αποτυχία αυθεντικοποίησης, αποτυχία εξουσιοδότησης, αποτυχία επικύρωσης, σύγκρουση κλειδιού ιδιοδυναμίας, υπέρβαση ορίου ρυθμού, ανύπαρκτος πόρος, σύγκρουση, αποτυχία προϋπόθεσης, υπερβολικά μεγάλο σώμα δεδομένων, μη υποστηριζόμενος τύπος περιεχομένου, λήξη χρόνου αναμονής ανάντη υπηρεσίας και εσωτερικό σφάλμα. Κάθε καταχώριση αποκτά σταθερό URI type, παράδειγμα σώματος και τεκμηριωμένη συμπεριφορά πελάτη. Η συμπεριφορά του πελάτη έχει σημασία: αυτή πρέπει να γράψει η ομάδα διασύνδεσης και, χωρίς καθοδήγηση, θα γράψει κάτι αυθαίρετο.

Ρωτήστε: Στα σφάλματα επικύρωσης, θα περιλαμβάνει το σώμα λεπτομέρειες ανά πεδίο και σε ποια μορφή; Το RFC επιτρέπει μέλη επέκτασης· ορίστε τα συγκεκριμένα.

7. Webhook, υπογραφή και προστασία από επανεκτέλεση

Αν η διασύνδεση περιλαμβάνει εξερχόμενα webhook, οι προδιαγραφές χρειάζονται ξεχωριστή ενότητα γι' αυτά. Αλγόριθμος υπογραφής (HMAC-SHA-256 με ξεχωριστό μυστικό ανά πελάτη είναι μια λειτουργική προεπιλογή), κανονικοποίηση (ποιες κεφαλίδες, ποια byte σώματος, ποια χρονική σήμανση), όνομα κεφαλίδας υπογραφής και ανοχή χρονικής σήμανσης. Η προστασία από επανεκτέλεση χωρά σε μία ρήτρα που απαιτεί από τον διακομιστή να απορρίπτει υπογεγραμμένα αιτήματα όταν η χρονική σήμανσή τους απέχει περισσότερο από πέντε λεπτά από το ρολόι του παραλήπτη.

Καθορίστε την πολιτική επανάληψης αποτυχημένων παραδόσεων webhook: όρια, αναμονή, χειρισμό ανεπίδοτων μηνυμάτων και τον τρόπο με τον οποίο η ομάδα διασύνδεσης μπορεί να ζητήσει επανάληψη αποστολής. Αν δεν υπάρχει μηχανισμός επανάληψης, η ενότητα τελειώνει με αυτή την παραδοχή — και εσείς αποφασίζετε για την παράδοση με βάση αυτό το δεδομένο.

Ρωτήστε: Ποια είναι η τεκμηριωμένη συμπεριφορά όταν το αποτύπωμα ενός webhook ταιριάζει με κάποιο που έχει ήδη παραδοθεί — σιωπηρή απόρριψη, σφάλμα ή παράδοση με ένδειξη; Είναι η αντίστροφη πλευρά της εισερχόμενης ιδιοδυναμίας και παραλείπεται διαρκώς.

8. Παρατηρησιμότητα και απόκριση σε περιστατικά

Οι περισσότερες προδιαγραφές διασύνδεσης σταματούν πριν από αυτή την ενότητα, που είναι ακριβώς εκείνη που αναζητάτε όταν κάτι χαλάσει. Περιλαμβάνει τουλάχιστον:

• Το όνομα της κεφαλίδας αναγνωριστικού συσχέτισης και τους κανόνες διάδοσής της. Το Trace Context του W3C (traceparent και tracestate) είναι η κατάλληλη προεπιλογή — αποτελεί οριστικοποιημένη σύσταση του W3C και το πρότυπο που παράγουν ήδη τα περισσότερα SDK και οι πύλες API (W3C Trace Context).
• Το διάστημα διατήρησης καταγραφών του προμηθευτή για αιτήματα διασύνδεσης και τη διαδικασία αίτησης ιστορικών ιχνών.
• Μια συγκεκριμένη διεύθυνση πίνακα παρακολούθησης στην οποία ο προμηθευτής θα παραχωρεί πρόσβαση ανάγνωσης κατά τα περιστατικά.
• Τη διαδρομή κλιμάκωσης και στις δύο πλευρές — ποιος απαντά στο τηλέφωνο, ποιος έχει την εξουσία να κηρύξει περιστατικό sev-1 και ποιο είναι το τεκμηριωμένο SLO χρόνου απόκρισης.

Ρωτήστε: Κατά τη διάρκεια περιστατικού, ποιος είναι ο μέγιστος χρόνος μέχρι να επιβεβαιώσει παραλαβή ένας άνθρωπος από την πλευρά του προμηθευτή και ποια είναι η τεκμηριωμένη διαδρομή κλιμάκωσης μετά από αυτό;

9. Εκδόσεις και πολιτική απόσυρσης

Αποφασίστε αν η έκδοση δηλώνεται στη διεύθυνση URL ή σε κεφαλίδα και τηρήστε την απόφαση. Δηλώστε το διάστημα προειδοποίησης απόσυρσης — έξι μήνες για αλλαγή που μεταβάλλει αποκρίσεις 2xx και δώδεκα μήνες για αφαίρεση τελικού σημείου είναι ένα εύλογο πλαίσιο του κλάδου. Απαιτήστε οι ειδοποιήσεις απόσυρσης να κοινοποιούνται τόσο με κεφαλίδα Sunset (σύμφωνα με το RFC 8594) όσο και με email στον ονομαστικά ορισμένο υπεύθυνο διασύνδεσης (RFC 8594).

Ρωτήστε: Ποιο είναι το πραγματικό ιστορικό ασύμβατων αλλαγών του προμηθευτή τους τελευταίους 24 μήνες; Η απάντηση αποκαλύπτει περισσότερα από την πολιτική.

Τι να αφήσετε εκτός

Ορισμένα πράγματα απουσιάζουν σκόπιμα από αυτό το πρότυπο, επειδή συστηματικά προκαλούν περισσότερη τριβή από όση αποτρέπουν.

Παραδείγματα κώδικα σε πολλές γλώσσες. Συντηρείτε το σχήμα OpenAPI και αφήστε τις γεννήτριες να παράγουν τον κώδικα πελάτη. Τα χειροποίητα παραδείγματα παλιώνουν και προβάλλονται ως έγκυρη αναφορά ενώ δεν είναι.

Διαγράμματα της ομαλής ροής. Τα διαγράμματα παλιώνουν άσχημα και σπάνια καλύπτουν τα σημεία που μετρούν (επαναλήψεις, αποτυχίες, μερικές καταστάσεις). Επενδύστε τον χρόνο σε πίνακες τρόπων αποτυχίας.

Ευσεβείς στόχοι επιπέδου υπηρεσίας. Βάλτε τα SLO στη σύμβαση, όχι στις προδιαγραφές. Οι προδιαγραφές περιγράφουν συμπεριφορά· οι συμβάσεις περιγράφουν συνέπειες.

Οι προδιαγραφές ως μηχανισμός λήψης αποφάσεων

Η καλύτερη στιγμή για να χρησιμοποιήσετε αυτό το πρότυπο είναι πριν γραφτεί η πρώτη γραμμή κώδικα διασύνδεσης, επειδή οι ερωτήσεις κάθε ενότητας αναγκάζουν τις ομάδες προϊόντος των προμηθευτών να δεσμευτούν εγγράφως. Αν η απάντηση στο «ποιο είναι το διάστημα διατήρησης του κλειδιού ιδιοδυναμίας» είναι «θα επανέλθουμε», μόλις εντοπίσατε έναν κίνδυνο. Καταγράψτε τον, προσαρμόστε το αντικείμενο του έργου και ξαναρωτήστε σε δύο εβδομάδες.

Οι διασυνδέσεις που παραδίδονται εγκαίρως είναι εκείνες των οποίων οι προδιαγραφές απάντησαν έγκαιρα στις δύσκολες ερωτήσεις, όχι εκείνες με τις περισσότερες ανασκοπήσεις κώδικα. Όσες πηγαίνουν άσχημα είναι σχεδόν πάντα εκείνες όπου οι προδιαγραφές γράφτηκαν μετά το πρώτο πρωτότυπο, προσαρμοσμένες εκ των υστέρων σε ό,τι έκανε ο κώδικας εκείνη την εβδομάδα. Η αντιστροφή αυτής της σειράς είναι η φθηνότερη διαθέσιμη επένδυση στην αξιοπιστία.

Η DevLume κάνει τη διερεύνηση της διασύνδεσης πρώτο παραδοτέο στα περισσότερα έργα — ευχαρίστως να μοιραστούμε την πλήρη εκδοχή αυτού του προτύπου προδιαγραφών, αν θέλετε ένα σημείο εκκίνησης βασισμένο σε πραγματικά έργα παραγωγής.