Εκδόσεις και συμβατότητα

Το API έχει μία κύρια έκδοση, την /v1, και αυτή μόνο μεγαλώνει. Μια ενσωμάτωση που γράφεται σήμερα συνεχίζει να λειτουργεί καθώς προστίθενται νέες δυνατότητες: τίποτα από όσα χρησιμοποιεί δεν μετονομάζεται, δεν αφαιρείται και δεν αποκτά νέα σημασία.

Ο αριθμός έκδοσης

Το API έχει έναν αριθμό έκδοσης, όπως 1.62.0. Αλλάζει με κάθε κυκλοφορία:

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

Μπορείτε να διαβάσετε ανά πάσα στιγμή την έκδοση που εξυπηρετεί μια διεύθυνση:

Το GET /v1/health έχει επίσης ένα version, αλλά πρόκειται για την έκδοση της κυκλοφορίας της Sursa που εξυπηρετεί τη διεύθυνση, όχι για την έκδοση του API.

Δεν επιλέγετε δευτερεύουσα έκδοση: κάθε αίτημα εξυπηρετείται από την τρέχουσα. Χάρη στους παρακάτω κανόνες, αυτό είναι ασφαλές.

Τι μπορεί να αλλάξει στο /v1

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

• Νέα τελικά σημεία.
• Νέες προαιρετικές παράμετροι και νέα πεδία αιτημάτων. Τα αιτήματα χωρίς αυτά συμπεριφέρονται όπως πριν.
• Νέα πεδία σε αποκρίσεις, αντικείμενα και συμβάντα.
• Νέες τιμές απαριθμήσεων στις αποκρίσεις, όπως μια νέα κατάσταση κάρτας ή ένας νέος τύπος συμβάντος.
• Νέοι κωδικοί σφάλματος και νέες κεφαλίδες απόκρισης.
• Όρια που γίνονται λιγότερο αυστηρά: μεγαλύτερο μέγιστο μήκος, ευρύτερο εύρος.
• Νέα διατύπωση στα κείμενα message των σφαλμάτων και στις περιγραφές.

Τι πρέπει να ανέχεται ο κώδικάς σας

• Αγνοείτε τα πεδία που δεν γνωρίζετε. Μην αποτυγχάνετε όταν μια απόκριση έχει περισσότερα πεδία από όσα περιμένετε και μη χρησιμοποιείτε αυστηρά σχήματα που τα απορρίπτουν.
• Δέχεστε τιμές απαρίθμησης που δεν γνωρίζετε. Κάθε απαρίθμηση σε μια απόκριση μπορεί να μεγαλώσει. Χειριστείτε μια άγνωστη τιμή ως «άλλο» και όχι ως σφάλμα.
• Παραλείπετε τους τύπους συμβάντων που δεν γνωρίζετε, τόσο στα webhooks όσο και στις ροές.
• Χειρίζεστε τους άγνωστους κωδικούς σφάλματος με βάση την κατάσταση HTTP: δείτε τον οδηγό Σφάλματα.
• Μην εξαρτάστε από τη σειρά των πεδίων στα αντικείμενα JSON ή από το ακριβές κείμενο των μηνυμάτων.

Τι δεν αλλάζει ποτέ στο /v1

• Μια διαδρομή, μια παράμετρος, ένα πεδίο ή μια τιμή απαρίθμησης δεν μετονομάζεται ούτε αφαιρείται ποτέ.
• Ο τύπος ενός πεδίου δεν αλλάζει ποτέ, και ένα πεδίο δεν αποκτά ποτέ νέα σημασία, όπως νέες μονάδες.
• Ένα αίτημα που γίνεται δεκτό σήμερα δεν απορρίπτεται αργότερα.
• Ο κωδικός κατάστασης μιας επιτυχούς απόκρισης μένει ίδιος.
• Οι κωδικοί σφάλματος διατηρούν τη σημασία τους, και το πεδίο detail των αποκρίσεων σφάλματος διατηρεί τη μορφή του.
• Οι τύποι συμβάντων δεν μετονομάζονται ούτε αφαιρούνται ποτέ, και το data τους μόνο αποκτά νέα πεδία.

Μη συμβατές αλλαγές

Αν χρειαστεί ποτέ μια μη συμβατή αλλαγή, θα κυκλοφορήσει ως νέα κύρια έκδοση, όπως η /v2, δίπλα στην /v1. Η /v1 συνεχίζει να λειτουργεί χωρίς αλλαγές, και οι δύο λειτουργούν παράλληλα.

Όταν μια διαδρομή πρόκειται να αποσυρθεί:

1. Επισημαίνεται ως deprecated στην προδιαγραφή και αναφέρεται στο ιστορικό αλλαγών μαζί με την ημερομηνία απενεργοποίησής της.
2. Οι αποκρίσεις της φέρουν τις κεφαλίδες Deprecation: true και Sunset: <date>.
3. Συνεχίζει να λειτουργεί για τουλάχιστον 180 ημέρες μετά την ανακοίνωση. Οι οργανισμοί των οποίων τα κλειδιά API τη χρησιμοποιούν ενημερώνονται γραπτώς τουλάχιστον 90 ημέρες νωρίτερα.
4. Μετά την ημερομηνία απόσυρσης, απαντά 410 με τον κωδικό api.gone για άλλες 90 ημέρες.

Παρακολουθείτε την κεφαλίδα Deprecation στα αρχεία καταγραφής ή στην παρακολούθησή σας: είναι το πρώτο σήμα ότι μια διαδρομή που χρησιμοποιείτε πρόκειται να καταργηθεί.

Πώς μένετε ενήμεροι

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