10 Σημαντικά στοιχεία της Τεκμηρίωσης API

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

Παρά τη γενική τους δημοτικότητα, δεν είναι κάθε API επιτυχημένο. Η υιοθέτηση και η χρήση ενός API καθορίζουν σε μεγάλο βαθμό την επιτυχία του. Για να αυξηθεί η υιοθέτηση, το API σας πρέπει να είναι εύκολο να βρεθεί και να χρησιμοποιηθεί.

Ο καλύτερος τρόπος για να το κάνετε αυτό είναι τεκμηριώνοντας το API σας λεπτομερώς. Αυτό περιλαμβάνει τη λεπτομέρεια κρίσιμων στοιχείων για να γίνουν πιο κατανοητά. Μάθετε μερικά από τα στοιχεία που πρέπει να συμπεριλάβετε στην τεκμηρίωση του API σας.

Τι είναι η Τεκμηρίωση API;

Η τεκμηρίωση API είναι τεχνικό περιεχόμενο που περιγράφει λεπτομερώς ένα API. Είναι ένα εγχειρίδιο που περιέχει όλες τις πληροφορίες που απαιτούνται για την εργασία με το API. Το έγγραφο καλύπτει τον κύκλο ζωής του API και οδηγίες για την ενοποίηση και τη χρήση των στοιχείων του.

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

Συντάκτες όπως τα Έγγραφα Google χρησιμοποιούνταν κάποτε ευρέως για επαγγελματική τεκμηρίωση API. Σήμερα, υπάρχουν πιο προηγμένα εργαλεία όπως το Document 360, το Confluence και οι Σελίδες GitHub. Αυτά τα εργαλεία βοηθούν στην ενσωμάτωση κειμένου και κώδικα για ευκολότερες ροές εργασίας.

1. Επισκόπηση και σκοπός του API

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

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

Ακολουθεί ένα παράδειγμα περιγραφής του API της Airbnb:

2. Μέθοδοι ελέγχου ταυτότητας και εξουσιοδότησης

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

Υπάρχουν διάφοροι τρόποι διασφάλισης ασφάλεια τελικού σημείου. Τα περισσότερα API χρησιμοποιούν κλειδί API. Αυτή είναι μια σειρά χαρακτήρων που ένας χρήστης μπορεί να δημιουργήσει από τον ιστότοπο και να χρησιμοποιήσει για έλεγχο ταυτότητας.

Η τεκμηρίωση του API θα πρέπει να καθοδηγεί τους χρήστες σχετικά με τον τρόπο ελέγχου ταυτότητας και εξουσιοδότησης της ταυτότητάς τους. Το παρακάτω διάγραμμα δείχνει πληροφορίες ελέγχου ταυτότητας API Twitter.

3. Τελικά σημεία, Μοτίβα URI και Μέθοδοι HTTP

Σε αυτήν την ενότητα, δείξτε πώς να αποκτήσετε πρόσβαση στον πόρο. Τα τελικά σημεία δείχνουν μόνο το τέλος της διαδρομής, εξ ου και το όνομά τους. Δείχνουν πρόσβαση στον πόρο και Μέθοδοι HTTP το τελικό σημείο αλληλεπιδρά με, δηλαδή GET, POST ή DELETE.

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

Το ακόλουθο δείγμα κώδικα δείχνει ένα τελικό σημείο χρήστη GET στο Instagram.

Παρε με? fields={fields}&access_token={access-token}

4. Μορφές αιτήματος και απάντησης

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

Ακολουθεί ένα δείγμα αιτήματος που μπορείτε να στείλετε στο API του LinkedIn.

ΠΑΙΡΝΩ https://api.linkedin.com/v2/{service}/1234

Και εδώ είναι ένα δείγμα απάντησης που μπορεί να επιστρέψει:

{
 "id": 1234,
 "relatedEntity": "urn: li: relatedEntity: 6789"
}

5. Παράμετροι και Κεφαλίδες

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

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

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

κεφαλίδες: {
 'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

Συμπεριλαμβάνετε παραμέτρους διαδρομής στο σώμα του τελικού σημείου ακριβώς στη διεύθυνση URL. Δείχνουν στον χρήστη πώς και πού να τοποθετήσει τις παραμέτρους και πώς θα εμφανιστεί η απάντηση. Οι λέξεις στα σγουρά τιράντες είναι παράμετροι.

Μπορείτε επίσης να χρησιμοποιήσετε άνω και κάτω τελεία ή άλλη σύνταξη για να αναπαραστήσετε τις παραμέτρους διαδρομής.

/service/myresource/user/{user}/bicycles/{bicycleId}

Με τις παραμέτρους ερωτήματος, πρέπει να τοποθετήσετε ένα ερωτηματικό (?) πριν από το ερώτημα σε ένα τελικό σημείο. Διαχωρίστε κάθε παράμετρο μετά από αυτό με ένα συμπλεκτικό σύμβολο (&). Η Microsoft διαθέτει καλή τεκμηρίωση για το Graph API.

6. Κωδικοί σφαλμάτων και χειρισμός σφαλμάτων

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

Το LinkedIn παρέχει τυπικούς κωδικούς σφάλματος HTTP για τη διαχείριση σφαλμάτων:

7. Δείγματα αποσπασμάτων κώδικα

Τα αποσπάσματα κώδικα αποτελούν βασικά μέρη της τεκμηρίωσής σας. Δείχνουν στους χρήστες πώς να ενσωματώσουν το API σε διάφορες γλώσσες και μορφές. Συμπεριλάβετε τον τρόπο εγκατάστασης και ενσωμάτωσης SDK (κιτ ανάπτυξης λογισμικού) σε διάφορες γλώσσες στην τεκμηρίωση.

Το RapidAPI έχει καλά παραδείγματα αποσπασμάτων κώδικα για προγραμματιστές:

9. Εκδόσεις API και αρχεία καταγραφής αλλαγών

Η έκδοση API είναι ένα ουσιαστικό μέρος του Σχεδιασμός API. Εξασφαλίζει την αδιάλειπτη παροχή υπηρεσιών στους χρήστες σας. Η έκδοση εκδόσεων μπορεί να βελτιώσει το API με νέες εκδόσεις χωρίς να επηρεάζει τις εφαρμογές πελατών.

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

Το Microsoft Graph API διαθέτει καλά τεκμηριωμένα αρχεία καταγραφής αλλαγών:

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

Η αξία της τεκμηρίωσης API

Εάν δημιουργήσετε ένα API για εμπορική αξία, η κατανάλωση καθορίζει την επιτυχία του. Και για να καταναλώσουν οι χρήστες το API σας, πρέπει να το καταλάβουν.

Η τεκμηρίωση δίνει ζωή σε ένα API. Εξηγεί λεπτομερώς τα στοιχεία σε απλή γλώσσα που πουλά την αξία και τη χρήση τους στους χρήστες. Οι χρήστες θα καταναλώσουν ευχαρίστως το API σας εάν έχουν εξαιρετική εμπειρία προγραμματιστή.

Η καλή τεκμηρίωση βοηθά επίσης στην απλοποίηση της συντήρησης και της κλιμάκωσης του API. Οι ομάδες που εργάζονται με το API μπορούν να χρησιμοποιήσουν τεκμηρίωση για να το διαχειριστούν.