Πίνακας περιεχομένων:
- Κανε τα μαθηματα σου
- Να είναι συνεπής
- Χρησιμοποιήστε το OAuth
- Ξεκινήστε νωρίς
- Γράψτε την καλή τεκμηρίωση
- Ανάπτυξη API: Κρατήστε το απλό
Είναι η φύση της ανάπτυξης λογισμικού. Οι προγραμματιστές δημιουργούν λογισμικό με τον τελικό χρήστη. Φαίνεται πολύ απλό, αλλά μερικές φορές αυτοί οι χρήστες είναι επίσης συνεργάτες προγραμματιστές. Δεν χρειάζονται πράγματα που τους χωρίζουν. Δεν χρειάζονται ούτε καν την απλότητα. Το μόνο που θέλουν είναι η πρόσβαση - ένας τρόπος να ενσωματώσετε το λογισμικό σας με το δικό τους. Αυτό είναι όπου έρχεται ένα API (interface προγραμματισμού εφαρμογών), ελπίζω να επισημάνω πέντε βήματα που μπορείτε να κάνετε για να δημιουργήσετε ένα επιτυχημένο API.
Κανε τα μαθηματα σου
Όταν πρόκειται για την ανάπτυξη λογισμικού, κανένας από μας δεν θέλει να ανακαλύψει τον τροχό. Σε αυτό το σημείο, σχεδόν όλες οι μεγάλες εταιρείες Ιστού έχουν API για τα προϊόντα λογισμικού τους. Μελετήστε αυτά τα API και προσπαθήστε να επισημάνετε τις διαφορετικές αποφάσεις σχεδιασμού που πήγαν στη δημιουργία τους.
Υπάρχουν πολλές διαφορετικές τεχνολογίες εκεί έξω, αλλά τα περισσότερα από τα API που θα δείτε θα χρησιμοποιούν είτε ένα περιβάλλον RESTful είτε SOAP. Εάν βρίσκεστε στο φράκτη ως προς το ποια διεπαφή API πρόκειται να χρησιμοποιήσετε, θα πρότεινα να προχωρήσετε με μια προσέγγιση RESTful χρησιμοποιώντας το πρωτόκολλο HTTP. Είναι απλούστερο από το SOAP, είναι πλέον πιο δημοφιλές και θα είναι πιο εύκολο να ξεκινήσετε με τη χρήση ενός λογισμικού που βασίζεται στο Web.
Να είναι συνεπής
Ένα από τα πράγματα που οι προγραμματιστές εκτιμούν περισσότερο είναι η συνοχή. Αυτό περιλαμβάνει, μεταξύ άλλων, διευθυνσιοδότηση, επιχειρήματα εισόδου, μορφές εξόδου και χειρισμό σφαλμάτων.
Όταν χρησιμοποιείτε μια προσέγγιση RESTful, υπάρχουν πολλά διαφορετικά σχήματα ονομασίας URI. Ο καθένας έχει τους οπαδούς του, οπότε επιλέξτε μόνο ένα και κολλήστε με αυτό. Το ίδιο συμβαίνει και με τη δομή εισόδου και εξόδου. Τα περισσότερα API υποστηρίζουν τη χρήση XML και JSON ως μορφές εισόδου και εξόδου. Θα πρότεινα την υποστήριξη και των δύο, αλλά επιλέγοντας ένα προεπιλεγμένο σχήμα.
Για εισροές, οι απαιτήσεις εισαγωγής σας θα πρέπει να ονομάζονται με συνέπεια και θα πρέπει να έχουν νόημα στο πλαίσιο της κλήσης API που κάνετε. Για την έξοδο, βεβαιωθείτε ότι χρησιμοποιείτε κοινές διατάξεις δομής δεδομένων. Εάν περιτυλίγετε την έξοδο μιας κλήσης API σε a
Είναι συνηθισμένη η πρακτική να συμπεριλαμβάνεται κάποιο είδος σημαίας κατάστασης στα δεδομένα εξόδου που στέλνετε πίσω στον πελάτη. Όταν χρησιμοποιείτε μια προσέγγιση RESTful API, αυτό πρέπει να γίνει χρησιμοποιώντας κωδικούς κατάστασης HTTP. Για παράδειγμα, εάν επεξεργαστείτε ένα αίτημα PUT σε ένα υπάρχον αντικείμενο δεδομένων, ο κωδικός κατάστασης HTTP που θα συμπεριλάβετε στην απάντησή σας θα διαφέρει ανάλογα με το αποτέλεσμα της αίτησης.
Αντί μιας αυθαίρετης σημαίας που υποδεικνύει την κατάσταση της κλήσης, μπορεί να χρησιμοποιηθεί ένας τυπικός κωδικός κατάστασης "200 OK" για να δηλώσει ότι η αίτηση ήταν επιτυχής, ενώ θα μπορούσε να χρησιμοποιηθεί ένας κωδικός κατάστασης "400 Bad Request" για να δηλώσει ότι το αίτημα ήταν δύσμορφος. Υπάρχουν αρκετοί κωδικοί κατάστασης HTTP που μπορούν να χρησιμοποιηθούν σε διαφορετικές καταστάσεις.
Χρησιμοποιήστε το OAuth
Τα περισσότερα προϊόντα λογισμικού θα περιλαμβάνουν κάποιο είδος ελέγχου ταυτότητας χρήστη, προκειμένου να έχουν πρόσβαση σε προστατευμένους πόρους για αυτόν τον χρήστη. Όταν πρόκειται για API, ο πελάτης που συλλέγει τα διαπιστευτήρια χρήστη να στείλει στον διακομιστή σας είναι κακή πρακτική. Εδώ μπαίνει το OAuth.
Το OAuth παρέχει πολλά πλεονεκτήματα έναντι του ελέγχου ταυτότητας με όνομα χρήστη / κωδικό πρόσβασης τρίτου μέρους. Πάνω απ 'όλα, ο πελάτης δεν έχει ποτέ πρόσβαση στα διαπιστευτήρια του χρήστη. Ο χρήστης ανακατευθύνεται στο διακομιστή σας όταν αυτός συνδεθεί. Αφού ο χρήστης συνδεθεί στον ιστότοπό σας, αυτός μεταφέρεται ξανά στον πελάτη, όπου ο πελάτης θα λάβει ένα αναγνωριστικό πρόσβασης για χρήση σε μελλοντικά αιτήματα σε προστατευμένους πόρους.
Ένα άλλο σημαντικό πλεονέκτημα της χρήσης του OAuth είναι η δυνατότητα του χρήστη να ακυρώσει την πρόσβαση του πελάτη ανά πάσα στιγμή. Εάν ο χρήστης αποφασίσει ότι, για οποιοδήποτε λόγο, δεν θέλουν πλέον τον πελάτη να έχει πρόσβαση σε προστατευμένους πόρους για λογαριασμό του, πηγαίνει απλώς σε μια διεπαφή που δημιουργήσατε και ακυρώνει την πρόσβαση του πελάτη.
Ξεκινήστε νωρίς
Ένα από τα πιο σημαντικά πράγματα που μπορείτε να κάνετε για να κάνετε το API σας επιτυχία είναι να ξεκινήσετε νωρίς. Όταν γράφετε τη λειτουργία αυτή για να δημιουργήσετε κάποια καταχώρηση στη βάση δεδομένων σας, προχωρήστε και πάρτε το επιπλέον χρόνο και γράψτε μια διεπαφή API για αυτό.Γράψτε την καλή τεκμηρίωση
Τίποτα δεν σκοτώνει ένα API γρηγορότερα από το να μην έχει καλή τεκμηρίωση. Ενώ ορισμένοι προγραμματιστές μπορούν να πάρουν ένα ανεπαρκώς τεκμηριωμένο API και να καταλάβουν πώς πρέπει να λειτουργούν, οι περισσότεροι δεν θα το θέλουν.
Θα πρέπει να τεκμηριώνετε κάθε κλήση API που διαθέτετε και να ταξινομήσετε τις κλήσεις API σας με βάση τον τύπο των δεδομένων που λειτουργούν. Μαζί με την τεκμηρίωση των τελικών σημείων για τις κλήσεις API οι ίδιοι, θα πρέπει να ορίσετε συστηματικά τα απαιτούμενα και προαιρετικά επιχειρήματα εισαγωγής καθώς και τις δομές δεδομένων εξόδου. Τα παράθυρα εισαγωγής πρέπει να εμφανίζουν μια προεπιλεγμένη τιμή εάν υπάρχει, και επίσης να αναφέρουν την αναμενόμενη μορφή δεδομένων όπως έναν αριθμό ή μια συμβολοσειρά. Τέλος, κάθε κλήση API θα πρέπει να περιλαμβάνει μια λίστα με τις συνθήκες σφάλματος και τους κωδικούς κατάστασης.
Για να ολοκληρώσετε την τεκμηρίωσή σας, φροντίστε να συμπεριλάβετε ένα ή δύο παραδείγματα για κοινά σενάρια εισόδου και εξόδου για κάθε κλήση API.
Ανάπτυξη API: Κρατήστε το απλό
Παρόλο που μπορεί να φανεί ότι η ανάπτυξη ενός API είναι μια πολύπλοκη προσπάθεια, η ιδέα ενός API από μόνο του δεν είναι μια νέα ιδέα και υπάρχει μεγάλη ποσότητα διαθέσιμης τεκμηρίωσης για κάθε θέμα που έχουμε αγγίξει εδώ. Απλά φροντίστε να χρησιμοποιείτε καλές πρακτικές όπου μπορείτε να τις βρείτε και να παρέχετε μια συνεπή, καλά τεκμηριωμένη διασύνδεση.
