Αναρωτηθήκατε ποτέ «Τι σκέφτονταν;» κατά την ενσωμάτωση μιας υπηρεσίας ιστού μέσω του API της; Εάν όχι, ήσασταν πολύ πιο τυχεροί από εμένα.
Οποιοσδήποτε προγραμματιστής λογισμικού ξέρει πόσο εύκολο είναι να αφήσουμε ένα έργο να μετατραπεί σε κώδικα σπαγγέτι και τα διαδικτυακά API δεν είναι λιγότερο επιρρεπή σε αποτέλεσμα μπερδεμένου ιστού. Αλλά δεν χρειάζεται να είναι έτσι. Στην πραγματικότητα, είναι δυνατό να σχεδιάσετε εξαιρετική API ιστού που πραγματικά θα κάνουν οι άνθρωποι απολαμβάνω χρησιμοποιώντας και ότι θα απολαύσετε επίσης τη δημιουργία. Αλλά πως? Η απάντηση σε αυτήν την ερώτηση είναι το περιεχόμενο αυτής της ανάρτησης.
Τις περισσότερες φορές όταν δημιουργείτε λύσεις, σχεδιάζετε για τελικούς χρήστες που δεν είναι προγραμματιστές ή γενικά δεν είναι τεχνικά εξελιγμένοι. Τους δίνετε μια γραφική διεπαφή και, αν έχετε κάνει τη δουλειά σας σωστά, έχετε συγκεντρώσει μια πολύ καλή ιδέα από αυτούς για το τι χρειάζονται για να κάνουν τη διεπαφή.
Αλλά Ανάπτυξη API είναι διαφορετικό. Σχεδιάζετε μια διεπαφή για προγραμματιστές , μάλλον χωρίς καν να γνωρίζουμε ποιοι είναι. Και όποιος κι αν είναι, θα έχει την τεχνική πολυπλοκότητα (ή τουλάχιστον θα πιστεύει ότι έχει την τεχνική πολυπλοκότητα) για να επισημάνει κάθε μικρό ελάττωμα στο λογισμικό σας. Οι χρήστες σας είναι πιθανό να είναι τόσο επικριτικοί για το API σας όσο και για τους δικούς τους, και θα τους αρέσει να το ασκούν κριτική.
Παρεμπιπτόντως, υπάρχει μέρος της ειρωνείας. Αν ο καθενας πρέπει να καταλάβει πώς να δημιουργήσει ένα API Ιστού που είναι εύκολο στη χρήση, είναι εσείς . Μετά από όλα, είστε μηχανικός λογισμικού όπως οι χρήστες του API σας, οπότε μοιράζεστε την οπτική τους. Ε;
Λοιπόν, ενώ σίγουρα καταλαβαίνουν την προοπτική τους, δεν είναι απαραίτητα μερίδιο η προοπτική τους. Όταν αναπτύσσετε ή βελτιώνετε τα δικα σου API, έχετε την προοπτική ενός API σχεδιαστής ενώ έχουν την προοπτική ενός API χρήστης .
Σχεδιαστές API συνήθως εστιάζουν σε ερωτήσεις όπως «Τι πρέπει να κάνει αυτή η υπηρεσία;» ή «Τι χρειάζεται αυτή η υπηρεσία;» , ενώ Χρήστες API επικεντρώνονται 'Πώς μπορώ να χρησιμοποιήσω αυτό το API για να κάνω αυτό που χρειάζομαι;' ή ακριβέστερα, 'Πώς μπορώ να ξοδέψω τη ελάχιστη προσπάθεια για να βρω αυτό που χρειάζομαι από αυτό το API;' .
Αυτές οι διαφορετικές ερωτήσεις οδηγούν σε δύο πολύ διαφορετικές προοπτικές. Ως αποτέλεσμα, η απαραίτητη προϋπόθεση για το σχεδιασμό α εξαιρετική Το API είναι να αλλάξετε την προοπτική σας από αυτήν του σχεδιαστή API σε εκείνη του χρήστη API. Με άλλα λόγια, ρωτήστε συνεχώς τον εαυτό σας τις ερωτήσεις που θα ρωτούσατε φυσικά εάν ήσασταν ο δικός σας χρήστης. Αντί να σκεφτόμαστε τι το API σας μπορώ να σκεφτείτε τους διαφορετικούς τρόπους που μπορεί να χρειαστεί ή να θέλει να είναι μεταχειρισμένος και στη συνέχεια εστιάστε στο να κάνετε αυτές τις εργασίες όσο το δυνατόν πιο εύκολη για τους χρήστες του API σας.
Παρόλο που αυτό μπορεί να ακούγεται εύκολο και προφανές, είναι εκπληκτικό το πώς σπάνια τα API φαίνεται να σχεδιάζονται με αυτόν τον τρόπο. Σκεφτείτε τα API που έχετε αντιμετωπίσει στην καριέρα σας. Πόσο συχνά φαίνεται να έχουν σχεδιαστεί λαμβάνοντας υπόψη αυτήν την προοπτική; Ο σχεδιασμός API Ιστού μπορεί να είναι δύσκολος.
Έτσι με αυτό είπε, ας προχωρήσουμε και να μιλήσουμε για το 5 Χρυσοί κανόνες για το σχεδιασμό ενός εξαιρετικού API Ιστού , και συγκεκριμένα:
Τεκμηρίωση. Ναι, ξεκινάω εδώ.
Μισείτε την τεκμηρίωση; Λοιπόν, μπορώ να κατανοήσω, αλλά βάζω το καπέλο 'προοπτική χρήστη' και θα στοιχηματίσω ότι το μόνο πράγμα που μισείτε περισσότερο από το να γράψετε τεκμηρίωση είναι να προσπαθήσετε να χρησιμοποιήσετε ένα API χωρίς έγγραφα. Αναπαύομαι την υπόθεσή μου
Η ουσία είναι ότι, εάν θέλετε κάποιος να χρησιμοποιήσει το API σας, η τεκμηρίωση είναι απαραίτητη. Απλά πρέπει να το κάνετε σωστά. Είναι το πρώτο πράγμα που θα δουν οι χρήστες, οπότε με κάποιους τρόπους μοιάζει με τη συσκευασία δώρου. Παρουσιάστε καλά και τα άτομα είναι πιο πιθανό να χρησιμοποιήσουν το API σας και να αντιμετωπίσουν τυχόν ιδιοσυγκρασίες.
Πώς γράφουμε λοιπόν καλή τεκμηρίωση;
Το σχετικά εύκολο μέρος είναι η τεκμηρίωση των ίδιων των μεθόδων API. δηλαδή, παραδείγματα αιτημάτων και απαντήσεων, μαζί με περιγραφές καθενός από τα στοιχεία και στα δύο. Ευτυχώς, υπάρχει ένας αυξανόμενος αριθμός εργαλείων λογισμικού που διευκολύνουν και απλοποιούν το έργο δημιουργίας τεκμηρίωσης. Εναλλακτικά, μπορείτε να γράψετε κάτι μόνοι σας, το οποίο διασχίζει το API, τα τελικά σημεία και τις λειτουργίες σας και δημιουργεί την αντίστοιχη τεκμηρίωση για εσάς.
scrum vs kanban vs lean
Αλλά αυτό που χωρίζει την εξαιρετική τεκμηρίωση από την επαρκή τεκμηρίωση είναι η συμπερίληψη παραδειγμάτων χρήσης και, ιδανικά, σεμιναρίων. Αυτό βοηθάει τον χρήστη να κατανοήσει το API σας και από πού να ξεκινήσει. Τους προσανατολίζει και τους βοηθά να φορτώσουν το API σας στον εγκέφαλό τους.
Για παράδειγμα, εάν οι προγραμματιστές του Twilio ήταν να απαριθμήσετε κάθε τάξη, κάθε μέθοδο και κάθε πιθανή απάντηση στο API τους, αλλά δεν ενοχλήσατε να αναφέρετε ότι μπορείτε να στείλετε ένα SMS, να παρακολουθήσετε μια κλήση ή να αγοράσετε έναν αριθμό τηλεφώνου μέσω του API τους, θα χρειαζόταν πραγματικά πολύ καιρό για τον χρήστη του API να βρει αυτές τις πληροφορίες και να τις κατανοήσει συνεκτικά. Μπορείτε να φανταστείτε να ταξινομήσετε ένα γιγαντιαίο δέντρο με τάξεις και μεθόδους χωρίς καμία εικόνα για το τι χρησιμοποιήθηκαν, εκτός από το όνομά τους; Ακούγεται φοβερό, σωστά; Αλλά αυτό ακριβώς κάνουν τόσοι πάροχοι API, αφήνοντας έτσι τα API τους αδιαφανή σε οποιονδήποτε εκτός από τον εαυτό τους. ο Οδηγός προγραμματιστή και API Rackspace CloudFiles είναι ένα τέτοιο παράδειγμα? είναι δύσκολο να φέρετε τα ρουλεμάν σας, εκτός εάν έχετε ήδη καταλάβει τι κάνουν και τι προσφέρουν.
Γι 'αυτό, γράψτε συνοπτικά μαθήματα που θα βοηθήσουν τον προγραμματιστή να λειτουργήσει γρήγορα, με τουλάχιστον ένα σκελετό για το τι προσπαθούν να κάνουν και στη συνέχεια να τους δείξετε προς την κατεύθυνση της πιο λεπτομερούς, πλήρως τεκμηριωμένης λίστας λειτουργιών, ώστε να μπορούν να επεκταθούν για το τι έχουν.
Μόλις τελειώσετε με την τεκμηρίωσή σας, βεβαιωθείτε ότι έχετε επικυρώσει ότι έχει νόημα για άτομα εκτός από εσάς. Στείλτε το σε άλλους προγραμματιστές στο δίκτυό σας, μην τους δώσετε άλλες οδηγίες παρά να τους δείξετε στην τεκμηρίωση και ζητήστε τους να ακολουθήσουν ένα σεμινάριο ή να δημιουργήσουν κάτι πραγματικά βασικό σε περίπου 15 λεπτά. Εάν δεν μπορούν να έχουν μια βασική ενσωμάτωση με το API σας σε 15 λεπτά, έχετε ακόμη περισσότερη δουλειά να κάνετε.
Για μερικά αξιοσημείωτα παραδείγματα εξαιρετικής και λεπτομερούς τεκμηρίωσης, ρίξτε μια ματιά Twilio , Τζάνγκο , και MailChimp . Κανένα από αυτά τα προϊόντα δεν είναι απαραίτητα τα καλύτερα στις αγορές τους (παρόλο που είναι όλα καλά προϊόντα), αλλά διακρίνουν τα θέματα με την παροχή ορισμένων από τα καλύτερα έγγραφα στην αγορά τους, γεγονός που σίγουρα διευκόλυνε την ευρεία αποδοχή και μερίδιο αγοράς τους.
Εάν έχετε χρησιμοποιήσει ποτέ API του Facebook , ξέρετε πόσο συχνά καταργούν και ξαναγράφουν πλήρως τα API τους. Ανεξάρτητα από το πόσο σέβεστε την κουλτούρα των χάκερ ή το προϊόν τους, η δική τους δεν είναι φιλική προς τους προγραμματιστές. Ο λόγος που εξακολουθούν να είναι επιτυχημένοι είναι επειδή έχουν ένα δισεκατομμύριο χρήστες, όχι επειδή το API τους είναι εξαιρετικό.
Αλλά πιθανότατα δεν έχετε την πολυτέλεια μιας τέτοιας τεράστιας βάσης χρηστών και μεριδίου αγοράς, οπότε θα χρειαστείτε ένα πολύ λιγότερο ασταθές API, διατηρώντας τις παλιές εκδόσεις σε λειτουργία και υποστηρίζονται για αρκετά μεγάλο χρονικό διάστημα. Ίσως ακόμη και χρόνια. Προς το σκοπό αυτό, ακολουθούν μερικές συμβουλές και κόλπα.
Ας υποθέσουμε, για παράδειγμα, ότι το API σας είναι προσβάσιμο μέσω της διεύθυνσης URL http://myapisite.com/api/widgets και παρέχει την απάντησή του σε μορφή JSON. Ενώ αυτό μπορεί να φαίνεται καλό στην πρώτη κοκκινίλα, τι συμβαίνει όταν πρέπει να τροποποιήσετε τη μορφή της απόκρισης JSON; Όλοι όσοι είναι ήδη ενσωματωμένοι σε εσάς θα σπάσουν. Ωχ.
Προχωρήστε λοιπόν στο μέλλον και εκδώστε το API σας από την αρχή, ενσωματώνοντας ρητά έναν αριθμό έκδοσης στη διεύθυνση URL (π.χ. http://myapisite.com/api/widgets?version=1 ή http://myapisite.com/api/widgets/v1) έτσι ώστε οι χρήστες να μπορούν να βασίζονται στην έκδοση 1 που λειτουργεί και να μπορούν να αναβαθμίσουν σε οποιαδήποτε επόμενη έκδοση όταν είναι έτοιμοι να το κάνουν. Εάν πρέπει να καταργήσετε μια προηγούμενη έκδοση σε κάποιο σημείο, προχωρήστε, αλλά δώστε αρκετή ειδοποίηση και προσφέρετε κάποιο είδος προγράμματος μετάβασης.
Ένα καλό σχήμα URL θα περιλαμβάνει σημαντικές εκδόσεις στο URL. Οποιαδήποτε αλλαγή στη μορφή εξόδου ή τους υποστηριζόμενους τύπους δεδομένων θα πρέπει να έχει ως αποτέλεσμα την αύξηση μιας νέας μεγάλης έκδοσης. Γενικά, είναι αποδεκτό να διατηρείτε την ίδια έκδοση εάν το μόνο που κάνετε είναι να προσθέσετε πλήκτρα ή κόμβους στην έξοδο σας, αλλά να είστε στην ασφαλή πλευρά, κάθε φορά που αλλάζει η έξοδος, χτυπήστε μια έκδοση.
Εκτός από το ότι είναι σταθερά με την πάροδο του χρόνου, τα API πρέπει να είναι εσωτερικά συνεπή. Έχω δει πολλά API που αλλάζουν ονόματα παραμέτρων ή μεθόδους POSTing δεδομένων, ανάλογα με το τελικό σημείο που χρησιμοποιείται. Αντ 'αυτού, θα πρέπει να χειρίζεστε κοινές παραμέτρους παγκοσμίως στο API σας και να χρησιμοποιείτε κληρονομιά ή κοινόχρηστη αρχιτεκτονική για να επαναχρησιμοποιείτε τις ίδιες συμβάσεις ονοματολογίας και τον χειρισμό δεδομένων με συνέπεια σε όλο το API σας.
Τέλος, πρέπει να εγγράψετε και να δημοσιεύσετε ένα changelog για να δείξετε διαφορές μεταξύ των εκδόσεων του API σας, ώστε οι χρήστες να γνωρίζουν ακριβώς πώς να κάνουν αναβάθμιση.
Σχετίζεται με: Tutorial Grape Gem: Πώς να φτιάξετε ένα REST-like API στο RubyΣκουπίδια μέσα, σκουπίδια έξω (GIGO) είναι ένα πολύ γνωστό μάντρα στους περισσότερους προγραμματιστές. Όπως εφαρμόζεται στον σχεδιασμό API Ιστού, αυτή η κατευθυντήρια αρχή τείνει να υπαγορεύει μια αρκετά άκαμπτη προσέγγιση για να ζητήσει επικύρωση. Ακούγεται υπέροχο, έτσι; Χωρίς χάος, κανένα πρόβλημα.
Ωστόσο, όπως με όλα, πρέπει να υπάρχει κάποια ισορροπία. Δεδομένου ότι δεν είναι δυνατόν να προβλέψουμε κάθε τρόπο που οι χρήστες θα θέλουν να χρησιμοποιήσουν την υπηρεσία σας και επειδή δεν είναι συνεπής κάθε πλατφόρμα πελάτη (δηλαδή, δεν έχει κάθε πλατφόρμα πολύ καλή υποστήριξη JSON, μια αξιοπρεπή βιβλιοθήκη OAuth, κ.λπ.), είναι καλό να έχετε τουλάχιστον κάποιο βαθμό ευελιξίας ή ανοχής σε σχέση με τους περιορισμούς εισόδου και εξόδου.
Για παράδειγμα, πολλά API θα υποστηρίξουν μια ποικιλία μορφών εξόδου, όπως JSON, YAML, XML, et. κ.λπ., αλλά θα υποστηρίζει μόνο τον καθορισμό της μορφής στο ίδιο το URL. Με το πνεύμα να παραμείνετε ευέλικτοι, θα μπορούσατε να επιτρέψετε να προσδιοριστεί και αυτό στη διεύθυνση URL (π.χ. /api/v1/widgets.json), ή μπορείτε επίσης να διαβάσετε και να αναγνωρίσετε ένα Accept: application/json Κεφαλίδα HTTP ή υποστήριξη μιας μεταβλητής ερωτηματολογίου όπως ?format=JSON και ούτω καθεξής.
Και ενώ είμαστε σε αυτό, γιατί να μην επιτρέπουμε τη μορφή που καθορίζεται να μην είναι διάκριση πεζών-κεφαλαίων, ώστε ο χρήστης να μπορεί να καθορίσει ?format=json επισης? Αυτό είναι ένα κλασικό παράδειγμα τρόπου ανακούφισης της περιττής απογοήτευσης για τον χρήστη του API σας.
Ένα άλλο παράδειγμα είναι η δυνατότητα για διαφορετικούς τρόπους εισαγωγής μεταβλητών. Έτσι, όπως έχετε μια ποικιλία μορφών εξόδου, επιτρέψτε και μια ποικιλία μορφών εισόδου (π.χ. απλές μεταβλητές POST, JSON, XML κ.λπ.). Θα πρέπει τουλάχιστον να υποστηρίζετε τυπικές μεταβλητές POST και πολλές σύγχρονες εφαρμογές υποστηρίζουν επίσης το JSON, οπότε αυτές οι δύο είναι ένα καλό μέρος για να ξεκινήσετε.
Το σημείο εδώ είναι ότι δεν πρέπει να υποθέσετε ότι όλοι μοιράζονται τις τεχνικές σας προτιμήσεις. Με λίγη έρευνα σχετικά με τον τρόπο λειτουργίας άλλων API και μέσω διαλόγου με άλλους προγραμματιστές, μπορείτε να συγκεντρώσετε άλλες πολύτιμες εναλλακτικές λύσεις που είναι χρήσιμες και να τις συμπεριλάβετε στο API σας.
Η ασφάλεια είναι προφανώς ένα από τα πιο σημαντικά πράγματα που πρέπει να ενσωματωθεί στην υπηρεσία ιστού σας, αλλά τόσοι πολλοί προγραμματιστές το καθιστούν γελοία δύσκολο στη χρήση. Ως πάροχος API, θα πρέπει να προσφέρετε χρήσιμα παραδείγματα για τον έλεγχο ταυτότητας και την εξουσιοδότηση κατά την πρόσβαση στο API σας. Αυτό δεν πρέπει να είναι ένα δύσκολο ζήτημα στο οποίο ένας τελικός χρήστης ξοδεύει ώρες δουλεύοντας. Ορίστε ως στόχο σας ότι είτε δεν χρειάζεται να γράψουν κώδικα, είτε χρειάζονται λιγότερο από 5 λεπτά για να τον γράψουν.
Για τα περισσότερα API, προτιμώ ένα απλό έλεγχος ταυτότητας βάσει διακριτικών , όπου το διακριτικό είναι ένα τυχαίο κατακερματισμό που έχει εκχωρηθεί στον χρήστη και μπορεί να το επαναφέρει σε οποιοδήποτε σημείο εάν έχει κλαπεί. Αφήστε το διακριτικό να περάσει μέσω POST ή κεφαλίδας HTTP. Για παράδειγμα, ο χρήστης θα μπορούσε (και θα έπρεπε) να στείλει ένα Διακριτικό SHA-1 ως μεταβλητή POST ή ως κεφαλίδα σε μορφή όπως 'Εξουσιοδότηση: da39a3ee5e6b4b0d3255bfef95601890afd80709'.
Επίσης, επιλέξτε ένα ασφαλές διακριτικό και όχι ένα σύντομο αριθμητικό αναγνωριστικό. Κάτι μη αναστρέψιμο είναι καλύτερο. Για παράδειγμα, είναι σχετικά απλό να δημιουργήσετε ένα διακριτικό SHA κατά τη δημιουργία του χρήστη και να το αποθηκεύσετε στη βάση δεδομένων. Στη συνέχεια, μπορείτε απλά να ζητήσετε τη βάση δεδομένων σας για τυχόν χρήστες που ταιριάζουν με αυτό το διακριτικό. Θα μπορούσατε επίσης να κάνετε ένα διακριτικό που δημιουργήθηκε με ένα μοναδικό αναγνωριστικό και μια τιμή αλατιού, κάτι σαν SHA(User.ID + 'abcd123') και, στη συνέχεια, να κάνετε ερώτημα για οποιονδήποτε χρήστη ταιριάζει. π.χ. where TokenFromPost = SHA(User.ID + 'abcd123').
Μια άλλη πολύ καλή επιλογή είναι OAuth 2 + SSL . Θα πρέπει να χρησιμοποιείτε SSL ούτως ή άλλως, αλλά το OAuth 2 είναι λογικά εύκολο να εφαρμοστεί από την πλευρά του διακομιστή και οι βιβλιοθήκες είναι διαθέσιμες για πολλές κοινές γλώσσες προγραμματισμού.
Εάν το API που έχετε δημιουργήσει υποτίθεται ότι είναι προσβάσιμο σε δημόσιο ιστότοπο μέσω JavaScript, πρέπει επίσης να βεβαιωθείτε ότι έχετε επικυρώσει μια λίστα διευθύνσεων URL ανά λογαριασμό για το διακριτικό. Με αυτόν τον τρόπο, κανείς δεν μπορεί να ελέγξει τις κλήσεις στο API σας, να κλέψει το διακριτικό από τον χρήστη σας και να το χρησιμοποιήσει για τον εαυτό του.
Εδώ είναι μερικά άλλα σημαντικά πράγματα που πρέπει να θυμάστε:
Λειτουργικότητα στη λίστα επιτρεπόμενων. Τα API σας επιτρέπουν γενικά να κάνετε βασικές λειτουργίες δημιουργίας, ανάγνωσης, ενημέρωσης και διαγραφής δεδομένων. Ωστόσο, δεν θέλετε να επιτρέψετε αυτές τις λειτουργίες για κάθε οντότητα, οπότε βεβαιωθείτε ότι η καθεμία έχει τη λίστα επιτρεπόμενων ενεργειών. Βεβαιωθείτε, για παράδειγμα, ότι μόνο εξουσιοδοτημένοι χρήστες μπορούν να εκτελούν εντολές όπως /user/delete/. Παρομοίως, όλες οι χρήσιμες κεφαλίδες που αποστέλλονται στο αίτημα του χρήστη πρέπει να επικυρωθούν και στη λίστα επιτρεπόμενων. Εάν επιτρέπετε κεφαλίδες τύπου περιεχομένου, βεβαιωθείτε ότι οτιδήποτε στέλνει ο χρήστης ταιριάζει στην πραγματικότητα με λίστα επιτρεπόμενων τύπων περιεχομένου. Εάν όχι, στείλτε ξανά ένα μήνυμα σφάλματος όπως μια μη αποδεκτή απάντηση 406. Η λίστα επιτρεπόμενων είναι σημαντική, καθώς δημιουργούνται αυτόματα πολλά API ή χρησιμοποιούν μια μαύρη λίστα, πράγμα που σημαίνει ότι πρέπει να είστε σαφείς για το τι όχι θέλω. Ωστόσο, ο χρυσός κανόνας ασφάλειας είναι να ξεκινήσετε με απολύτως τίποτα, και να επιτρέπετε μόνο ρητά αυτό που εσείς κάνω θέλω.
πώς να χρησιμοποιήσετε το πλαίσιο ελατηρίου
Προστατέψτε τον εαυτό σας από Συλλογή αιτήσεων μεταξύ ιστότοπων (CSRF) . Εάν επιτρέπετε τον έλεγχο ταυτότητας περιόδου λειτουργίας ή cookie, πρέπει να βεβαιωθείτε ότι προστατεύετε τον εαυτό σας από επιθέσεις CSRF. ο Άνοιγμα έργου ασφαλείας εφαρμογών ιστού (OWASP) παρέχει χρήσιμες οδηγίες για τρόποι για την αποτροπή αυτών των τρωτών σημείων .
Επικυρώστε την πρόσβαση σε πόρους. Σε κάθε αίτημα, πρέπει να επαληθεύσετε ότι ο χρήστης έχει στην πραγματικότητα πρόσβαση στο συγκεκριμένο αντικείμενο στο οποίο αναφέρεται. Επομένως, εάν έχετε ένα τελικό σημείο για να δείτε τα στοιχεία της πιστωτικής κάρτας ενός χρήστη (π.χ. /account/card/view/152423), βεβαιωθείτε ότι το αναγνωριστικό '152423' αναφέρεται σε έναν πόρο στον οποίο ο χρήστης έχει πράγματι εξουσιοδότηση πρόσβασης.
Επικυρώστε όλες τις εισόδους. Όλες οι είσοδοι από έναν χρήστη πρέπει να αναλυθούν με ασφάλεια, κατά προτίμηση χρησιμοποιώντας μια γνωστή βιβλιοθήκη εάν χρησιμοποιείτε περίπλοκες εισόδους όπως XML ή JSON. Μην φτιάξετε τον δικό σας αναλυτή, ή είστε για έναν κόσμο πληγών.
Αυτός είναι πραγματικά ο πιο σημαντικός κανόνας στη δέσμη και βασίζεται σε όλους τους άλλους. Όπως ανέφερα κατά τη διάρκεια του κανόνα τεκμηρίωσης, δοκιμάστε το με άτομα που είναι νέα στο API σας. Βεβαιωθείτε ότι μπορούν να ξεκινήσουν να λειτουργούν με τουλάχιστον μια βασική εφαρμογή του API σας, ακόμα κι αν ακολουθεί έναν οδηγό, μέσα σε λίγα λεπτά. Νομίζω ότι τα 15 λεπτά είναι ένας καλός στόχος.
Ακολουθούν ορισμένες συγκεκριμένες προτάσεις για τη διευκόλυνση και τη διευκόλυνση της υιοθέτησης του API σας:
Βεβαιωθείτε ότι οι χρήστες μπορούν πραγματικά να χρησιμοποιούν το API σας και ότι λειτουργεί την πρώτη φορά, κάθε φορά. Ζητήστε από νέους χρήστες να εφαρμόζουν το API σας περιστασιακά για να επαληθεύσουν ότι δεν προκαλεί σύγχυση κατά κάποιον τρόπο με τον οποίο έχετε συνηθίσει.
Κρατήστε το απλό. Μην κάνετε αυθεντικό έλεγχο ταυτότητας. Μην κάνετε κάποιο τρελό προσαρμοσμένο σχήμα URL. Μην ανακαλύψετε ξανά το σαπούνι, το JSON ή το REST ή οτιδήποτε άλλο. Χρησιμοποιήστε όλα τα εργαλεία που μπορείτε να έχουν ήδη εφαρμοστεί και είναι ευρέως αποδεκτά, έτσι ώστε οι προγραμματιστές να πρέπει να μάθουν μόνο το API σας, όχι το API + 10 που κρύβετε τις νέες τεχνολογίες.
Παροχή βιβλιοθηκών για συγκεκριμένη γλώσσα για διασύνδεση με την υπηρεσία σας. Υπάρχουν μερικά ωραία εργαλεία για να δημιουργήσετε αυτόματα μια βιβλιοθήκη για εσάς, όπως Αιγοκάμηλος ή Apache Thrift . Προς το παρόν η Alpaca υποστηρίζει Node, PHP, Python και Ruby. Η Thrift υποστηρίζει C ++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C #, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi και άλλα.
Απλοποιήστε κάθε απαραίτητη εγγραφή. Εάν δεν αναπτύσσετε ένα API ανοιχτού κώδικα ή εάν υπάρχει οποιαδήποτε διαδικασία εγγραφής, βεβαιωθείτε ότι κατά την εγγραφή, ένας χρήστης κατευθύνεται πολύ γρήγορα σε ένα σεμινάριο. Και κάντε τη διαδικασία εγγραφής πλήρως αυτοματοποιημένη χωρίς να χρειάζεται ανθρώπινη αλληλεπίδραση εκ μέρους σας.
Παρέχετε εξαιρετική υποστήριξη. Ένα μεγάλο εμπόδιο στην υιοθέτηση είναι η έλλειψη υποστήριξης. Πώς θα χειριστείτε και θα απαντήσετε σε μια αναφορά σφαλμάτων; Τι γίνεται με την ασαφή τεκμηρίωση; Ένας μη εξελιγμένος χρήστης; Τα φόρουμ, οι εντοπιστές σφαλμάτων και η υποστήριξη μέσω email είναι φανταστικές εκκινήσεις, αλλά βεβαιωθείτε ότι όταν κάποιος δημοσιεύει ένα σφάλμα, το αντιμετωπίζετε πραγματικά. Κανείς δεν θέλει να δει ένα φόρουμ πόλης-φάντασμα ή μια τεράστια λίστα σφαλμάτων που δεν έχουν αντιμετωπιστεί.
Οι υπηρεσίες Ιστού και τα API τους αφθονούν. Δυστυχώς, η συντριπτική πλειοψηφία είναι δύσκολο να χρησιμοποιηθεί. Οι λόγοι κυμαίνονται από κακή σχεδίαση, έως έλλειψη τεκμηρίωσης, έως μεταβλητότητα, έως ανεπίλυτα σφάλματα ή, σε ορισμένες περιπτώσεις, όλα τα παραπάνω.
Ακολουθώντας τις οδηγίες σε αυτήν την ανάρτηση, θα διασφαλίσετε ότι το API ιστού σας είναι καθαρό, καλά τεκμηριωμένο και εύχρηστο. Τέτοια API είναι πραγματικά σπάνια και επομένως είναι πολύ πιο πιθανό να υιοθετηθούν και να χρησιμοποιηθούν ευρέως.
Σχετίζεται με: Ένα σεμινάριο για την αντίστροφη μηχανική του ιδιωτικού API του λογισμικού σας: Χάραξη του καναπέ σας
