Το REST API αποτελεί σήμερα τον πιο διαδεδομένο τρόπο επικοινωνίας μεταξύ διαφορετικών συστημάτων. Είναι πρακτικά ένα πρότυπο, μια διεπαφή η οποία είναι ανεξάρτητη από γλώσσες προγραμματισμού και συνήθως, η αμφιδρομη επικοινωνία βασίζεται στο http πρωτοκολλο. Πριν προχωρήσουμε παρακάτω να διευκρινίσουμε πώς REST API ΔΕΝ ορίζουμε ένα δυναμικό url που απλά επιστρέφει δεδομένα σε μορφή json.
Όπως είπαμε, το REST API είναι ανεξάρτητο από γλώσσες προγραμματισμού, συνεπώς τα όσα θα περιγράψουμε παρακάτω μπορούν να εφαρμοστούν σε οποιαδήποτε γλώσσα προγραμματισμού, όπως για παράδειγμα στην PHP ή την Golang, που αποτελούν και δυο αγαπημένες μου γλώσσες προγραμματισμού.
Η αξία του να σχεδιάσουμε ένα σωστό API είναι ιδιαίτερα σημαντική, διότι θα κάνουμε πιο ευκολη την ζωή όσων θέλουν να “συνδεθούν” μαζί μας. Αυτοί μπορεί να είναι οι web front end developers της ομάδας μας, οι mobile developers, οι backend developers και φυσικά εξωτερικοί πάροχοι. Κάνοντας την ζωή τους πιο εύκολη κάνουμε όπως είναι αυτονόητο και εμείς την δική μας δουλειά πιο σωστή και φυσικά πιο ξεκούραστη.
Tip1 : Σταθερή δομή
Κάθε response του API μας οφείλει να έχει σταθερή δομή στο ανώτερο επίπεδο, εκτός φυσικά των μεταβλητών δεδομένων. Για παράδειγμα:
Τα 3 ανώτερα επίπεδα του συγκεκριμένου παραδείγματος είναι το data, pagination, errors. Αυτά πρέπει να σταθερά ως προς την ονομασία. Το data θα περιέχει κάθε φορά τα δεδομένα, το pagination θα έχει πληροφορίες για την σελιδοποιηση αν αυτή υπάρχει αλλιώς μπορεί να είναι null ή και να μην εμφανίζεται υπο περιπτώσεις και το errors είναι ένα array το οποίο θα περιέχει σχετικές πληροφορίες.
Συχνά μέσα στα data προσθέτουμε ένα επιπλέον επίπεδο ( π.χ “users” : [] το οποίο θεωρούμε πώς λειτουργεί πληροφοριακά ( δεδομένα/χρήστες αλλά αυτό το info το δίνει το endpoint όπως θα δούμε παρακάτω ). Πρακτικά αυτή η προσέγγιση λειτουργεί πλεονασματικά βάζοντας λιθαράκι στην αυξηση της πολυπλοκότητας, της μείωσης της ταχύτητας, της αύξησης του όγκου των δεδομένων και της εμφάνισης προβλημάτων καθώς όποιος κάνει integration μαζί μας θα πρέπει να θυμάται να βάζει αντί για σκέτο και καθαρό .data για να πάρει τα δεδομένα κατι της μορφής .data.users, .data.customers, .data.products.
Tip2 : Χρήση των κατάλληλων http status codes αντί για 200 ok
Κάθε response του API μας οφείλει να παρέχει το αντίστοιχο status code ανάλογα την έκβαση του αιτήματος. Για παράδειγμα όταν επιστρέφουμε δεδομένα πρέπει να επιστρέφουμε 200, όταν δημιουργούμε ένα πόρο να επιστρέφουμε 201 μαζί με το created object κάτι που θα βοηθήσει στο integration testing μας αλλά πιθανότατα και τους front devs, ώστε για παράδειγμα να μεταβεί ο χρήστης στο “προφίλ” του δημιουργημένου κάθε φορά object, όταν κάτι δεν υπάρχει να επιστρέφουμε 404 κ.α
Tip3 : Χρήση των κατάλληλων http methods
Εξαιρετικά σημαντικό σε ένα REST API να τηρούμε τα http methods χωρίς να κάνουμε χρήση δικών μας εφευρέσεων. Το πόσο καθαρό και χρήσιμο είναι αυτό μπορείτε να το καταλάβετε παρακάτω που έχουμε περίπτωση με ίδιο url.
[GET] /users/5 -> Φέρε μου πληροφορίες για τον χρήστη με ID 5
[UPDATE] /users/5 -> Ενημέρωσε τις πληροφορίες του χρήστη με ID 5
[DELETE] /users/5 -> Διέγραψε τον χρήστη με ID 5
Tip4 : Endpoints που δείχνουν την οντότητα
Τα endpoints μας μπορούμε να τα φανταστούμε και σαν δομή φακέλων. Για παράδειγμα για να πάρουμε τους χρήστες ενός συγκεκριμένου διαγωνισμού ενός συγκεκριμένου πελάτη της εφαρμογής μας μπορούμε να ορίσουμε το endpoint μας ως εξής:
[GET] customers/{customer_id}
/contests/{contest_id}/users
Μετάφραση: Απο τους πελάτες (της εφαρμογής μου), άνοιξε τον πελάτη με ID 5, πήγαινε στους διαγωνισμούς του, άνοιξε τον διαγωνισμό με ID 1 και φέρε τους χρήστες του.
Το παραπάνω είναι καθαρό, μας επιτρέπει με αυτόματο τρόπο να εφαρμόσουμε authorization σε κεντρικό σημείο, για το αν για παράδειγμα ο συνδεδεμένος χρήστης έχει read access στον πελάτη 5 και είναι σαφώς πιο σωστό από το να γράφαμε κατι του στυλ
/getUsers?customer_id=5&contest_id=1
Tip5 : Consistency
Τα δεδομένα που στέλνουμε πρέπει να έχουν την ίδια δομή και μορφή με αυτή που λαμβάνουμε. Για παράδειγμα δεν μπορούμε να στέλνουμε το email ως email στο GET αλλά στο POST ή PUT να το ζητάμε ως “user_email”. Εξαιρετικά σημαντικό είναι επίσης και ο τύπος δεδομένων να ειναι σταθερός μεταξύ της αμφίδρομης επικοινωνίας και φυσικά να υπάρχει σχετικό και αυστηρό validation. Για παράδειγμα η πληροφορία “is_pet_friendly” : 1 πρέπει να στέλνετε/λαμβάνετε πάντα ως ακέραιος. Αν λάβουμε “is_pet_friendly” : “1” το οποίο είναι τύπος αλφαριθμητικό(string) θα πρέπει να μην περάσει.
Tip6 : API documentation
Το documentation του API μας είναι απαραίτητο να υπάρχει και μπορούμε εύκολα να το γράφουμε - προσαρμόζουμε ενώ κάνουμε συγγραφή και manual testing το API μας. Το Postman για παράδειγμα είναι ένα εξαιρετικό εργαλείο που μας παρέχει εκτός των πολλών άλλων επιλογών και δυνατοτητα για doc. Ένα κακό API documentation ή ακόμα χειρότερα ένα ανύπαρκτο API documentation θα δημιουργήσει πολλά προβλήματα.
Προσίλης Αργύρης
Software engineer
