Η αντιπροσωπευτική μεταφορά κατάστασης, κοινώς γνωστή ως REST, είναι ένα αρχιτεκτονικό στυλ - ένα σύνολο περιορισμών που χρησιμοποιούνται για την εφαρμογή υπηρεσιών χωρίς κατάσταση που εκτελούνται σε HTTP. Ένα RESTful API είναι αυτό που συμμορφώνεται με τους περιορισμούς REST. Μπορείτε να δημιουργήσετε RESTful API χρησιμοποιώντας πολλές διαφορετικές γλώσσες προγραμματισμού.
Η διατήρηση της συμβατότητας μεταξύ διαφορετικών εκδόσεων του API σας είναι ύψιστης σημασίας για να διασφαλιστεί ότι το API σας θα παραμείνει συμβατό με όλους τους πελάτες που το καταναλώνουν. Αυτό το άρθρο παρουσιάζει μια συζήτηση για το πώς μπορείτε να διατηρήσετε τη συμβατότητα με τα RESTful API σας.
Παράδειγμα συμβατότητας API
Ας υποθέσουμε ότι έχετε ένα API στην παραγωγή που καταναλώνεται από διαφορετικούς πελάτες. Τώρα, εάν θέλετε να προσθέσετε περισσότερη λειτουργικότητα στο API, θα πρέπει να διασφαλίσετε ότι οι πελάτες που χρησιμοποιούν το παλιό API θα μπορούν να χρησιμοποιούν είτε το νέο API είτε το παλιό. Με άλλα λόγια, πρέπει να διασφαλίσετε ότι η υπάρχουσα λειτουργικότητα του API θα παραμείνει ανέπαφη κατά την προσθήκη της νέας λειτουργικότητας.
Ένα API είναι συμβατό προς τα πίσω, εάν ένας πελάτης (ένα πρόγραμμα που έχει συνταχθεί για την κατανάλωση του API) που μπορεί να λειτουργήσει με μια έκδοση του API μπορεί να λειτουργήσει με τον ίδιο τρόπο με τις μελλοντικές εκδόσεις του API. Με άλλα λόγια, ένα API είναι συμβατό με παλαιότερες εκδόσεις, εάν οι πελάτες πρέπει να είναι σε θέση να συνεργάζονται με μια νέα έκδοση του API χωρίς προβλήματα.
Ας το καταλάβουμε με ένα παράδειγμα. Ας υποθέσουμε ότι έχετε μια μέθοδο API που ονομάζεται GetOrders όπως φαίνεται στο απόσπασμα κώδικα παρακάτω.
[HttpGet][Διαδρομή ("GetOrders")]
δημόσια IActionResult GetOrders (int customerId, int orderId = 0)
{
var result = _orderService.GetOrdersForCustomer (
customerId, orderId);
επιστροφή ΟΚ (αποτέλεσμα)
}
Η μέθοδος δράσης GetOrders δέχεται αναγνωριστικό πελάτη και αναγνωριστικό παραγγελίας ως παραμέτρους. Σημειώστε ότι η δεύτερη παράμετρος, orderID, είναι προαιρετική. Η ιδιωτική μέθοδος GetOrdersForCustomer δίνεται παρακάτω.
ιδιωτική λίστα GetOrdersForCustomer (int customerId, int orderId){
// Γράψτε κώδικα εδώ για να επιστρέψετε μία ή περισσότερες εγγραφές παραγγελιών
}
Η μέθοδος GetOrdersForCustomer επιστρέφει όλες τις παραγγελίες ενός πελάτη, εάν η παραγγελία που του πέρασε ως παράμετρος είναι 0. Εάν η παραγγελία δεν είναι μηδενική, επιστρέφει μία παραγγελία που σχετίζεται με τον πελάτη που προσδιορίστηκε από τον πελάτη που μεταβιβάστηκε ως όρισμα.
Δεδομένου ότι η δεύτερη παράμετρος της μεθόδου δράσης GetOrders είναι προαιρετική, μπορείτε απλώς να περάσετε το customerId. Τώρα, εάν αλλάξετε τη δεύτερη παράμετρο της μεθόδου δράσης GetOrders για να την κάνετε υποχρεωτική, οι παλιοί πελάτες του API δεν θα μπορούν πλέον να χρησιμοποιούν το API.
[HttpGet][Διαδρομή ("GetOrders")]
δημόσια IActionResult GetOrders (int customerId, int orderId)
{
var result = _orderService.GetOrdersForCustomer
(customerId, orderId);
επιστροφή ΟΚ (αποτέλεσμα)
}
Και, έτσι μπορείτε να σπάσετε τη συμβατότητα του API σας! Η ενότητα που ακολουθεί περιγράφει τις βέλτιστες πρακτικές που μπορούν να υιοθετηθούν για να καταστήσουν το API σας συμβατό προς τα πίσω.
Συμβουλές συμβατότητας API
Τώρα που γνωρίζουμε ποιο είναι το πρόβλημα, πώς σχεδιάζουμε τα APIs με τον προτεινόμενο τρόπο; Πώς διασφαλίζουμε ότι το RESTful API μας είναι συμβατό προς τα πίσω; Σε αυτήν την ενότητα παρατίθενται μερικές από τις βέλτιστες πρακτικές που μπορούν να ακολουθηθούν ως προς αυτό.
Βεβαιωθείτε ότι έχουν περάσει οι δοκιμές της μονάδας
Θα πρέπει να έχετε γράψει δοκιμές που θα επαληθεύουν εάν η λειτουργικότητα είναι ανέπαφη με μια νέα έκδοση του API. Οι δοκιμές θα πρέπει να γραφτούν με τέτοιο τρόπο ώστε να αποτύχουν εάν υπάρχουν προβλήματα συμβατότητας προς τα πίσω. Στην ιδανική περίπτωση, θα πρέπει να έχετε μια δοκιμαστική σουίτα για δοκιμές API που θα αποτύχει και θα ειδοποιηθεί όταν υπάρχουν προβλήματα με τη συμβατότητα του API προς τα πίσω. Θα μπορούσατε επίσης να έχετε μια αυτόματη δοκιμαστική σουίτα συνδεδεμένη στον αγωγό CI / CD που ελέγχει για συμβατότητα προς τα πίσω και ειδοποιήσεις όταν υπάρχει παραβίαση.
Ποτέ μην αλλάζετε τη συμπεριφορά των κωδικών απόκρισης HTTP
Δεν πρέπει ποτέ να αλλάξετε τη συμπεριφορά των κωδικών απόκρισης HTTP στο API σας. Εάν το API σας επιστρέψει 500 όταν αποτύχει να συνδεθεί στη βάση δεδομένων, δεν θα πρέπει να το αλλάξετε σε 200. Ομοίως, εάν επιστρέφετε HTTP 404 όταν εμφανίζεται μια εξαίρεση, και οι πελάτες σας χρησιμοποιούν αυτό και το αντικείμενο απόκρισης για να προσδιορίσουν τι πήγε λάθος, η αλλαγή αυτής της μεθόδου API για την επιστροφή HTTP 200 θα καταστρέψει εντελώς την συμβατότητα προς τα πίσω.
Ποτέ μην αλλάζετε παραμέτρους
Αποφύγετε τη δημιουργία μιας νέας έκδοσης του API όταν κάνετε μόνο μικρές αλλαγές, καθώς μπορεί να είναι υπερβολική. Μια καλύτερη προσέγγιση είναι να προσθέσετε παραμέτρους στις μεθόδους API για να ενσωματώσετε τη νέα συμπεριφορά. Με τον ίδιο τρόπο, δεν πρέπει να καταργήσετε παραμέτρους από μια μέθοδο API ή να αλλάξετε μια παράμετρο από προαιρετική σε υποχρεωτική (ή αντίστροφα), καθώς αυτές οι αλλαγές θα σπάσουν το API και οι παλιοί πελάτες ή οι καταναλωτές του API δεν θα είναι πλέον σε θέση για να εργαστείτε με το API.
Έκδοση του API σας
Η έκδοση των API είναι μια καλή πρακτική. Η εκδοχή βοηθά το API σας να είναι πιο ευέλικτο και προσαρμόσιμο στις αλλαγές, διατηρώντας παράλληλα τη λειτουργικότητα ανέπαφη. Σας βοηθά επίσης να διαχειριστείτε καλύτερα τις αλλαγές στον κώδικα και να επιστρέψετε πιο εύκολα στον παλιό κώδικα εάν ο νέος κώδικας προκαλεί προβλήματα. Θα πρέπει να έχετε μια διαφορετική έκδοση του RESTful API σας με κάθε σημαντική έκδοση.
Παρόλο που το REST δεν παρέχει συγκεκριμένες οδηγίες για την έκδοση API, μπορείτε να εκδώσετε το API σας με τρεις διαφορετικούς τρόπους: καθορίζοντας τις πληροφορίες έκδοσης στο URI, αποθηκεύοντας τις πληροφορίες έκδοσης στην επικεφαλίδα προσαρμοσμένου αιτήματος και προσθέτοντας τις πληροφορίες εκδόσεων στο HTTP Accept επί κεφαλής. Παρόλο που η έκδοση μπορεί να σας βοηθήσει να διατηρήσετε το API σας, θα πρέπει να αποφύγετε να διατηρείτε πολλές εκδόσεις του API για να επισημάνετε συχνές κυκλοφορίες. Αυτό θα γίνει γρήγορα δυσκίνητο και αντιπαραγωγικό.
Άλλες βέλτιστες πρακτικές API
Δεν πρέπει ποτέ να αλλάζετε τη ριζική διεύθυνση URL ενός API ή να τροποποιείτε τις υπάρχουσες παραμέτρους συμβολοσειράς ερωτήματος. Τυχόν πρόσθετες πληροφορίες πρέπει να προστεθούν ως προαιρετική παράμετρος σε μια μέθοδο API. Πρέπει επίσης να διασφαλίσετε ότι τα προαιρετικά ή υποχρεωτικά στοιχεία που μεταβιβάζονται σε ένα API ή επιστρέφονται από ένα API δεν διαγράφονται ποτέ.
Οι αλλαγές σε ένα RESTful API είναι αναπόφευκτες. Ωστόσο, εκτός εάν τηρείτε τις βέλτιστες πρακτικές και βεβαιωθείτε ότι το API είναι συμβατό με παλαιότερες εκδόσεις, οι αλλαγές σας μπορούν να καταστρέψουν τη συμβατότητα του API με τους υπάρχοντες πελάτες. Ένα API που βρίσκεται σε παραγωγή και καταναλώνεται από πολλούς πελάτες θα πρέπει πάντα να είναι συμβατό με τις εκδόσεις.
