Τι μπορεί να κάνει ένα API για την ομάδα περιεχομένου σας
Ένα API συνδέει δύο ψηφιακά συστήματα χωρίς να απαιτεί από τους χρήστες να αντιγράφουν και να επικολλούν περιεχόμενο κάθε φορά. Για παράδειγμα, ένα σύστημα διαχείρισης περιεχομένου μπορεί να στείλει επιλεγμένο κείμενο σε μια υπηρεσία αναγνώρισης ομιλίας και να λάβει πίσω το αποτέλεσμα. Το περιεχόμενο παραμένει στο οικείο CMS για την ομάδα σύνταξης, ενώ η τεχνική σύνδεση χειρίζεται την ανταλλαγή στο παρασκήνιο.
Το API δεν αποφασίζει αυτόματα ποιο περιεχόμενο πρέπει να δημοσιευτεί. Παρέχει έναν σαφώς καθορισμένο τρόπο για την υποβολή αιτήματος δεδομένων και την επιστροφή αποτελεσμάτων. Η ομάδα εξακολουθεί να καθορίζει ποια σελίδα επεξεργάζεται, ποια έκδοση χρησιμεύει ως πηγή και εάν ένα αποτέλεσμα πρέπει να ελεγχθεί πριν από τη δημοσίευση. Αυτός ο διαχωρισμός προστατεύει την συντακτική ευθύνη.
Επομένως, ένα καλό σημείο εκκίνησης δεν απαιτεί πλήρη αυτοματοποίηση. Ένας μόνο, συχνά χρησιμοποιούμενος τύπος περιεχομένου αρκεί για να κατανοηθούν τα οφέλη. Αυτό θα μπορούσε να είναι το κείμενο περιγραφής μιας υπηρεσίας. Εάν η αποστολή, η λήψη, η αναθεώρηση και η αποθήκευση λειτουργούν αξιόπιστα εκεί, περαιτέρω περιεχόμενο μπορεί να προστεθεί αργότερα σε μια σταθερή βάση. Η περιορισμένη έναρξη καθιστά επίσης σαφές εάν η σύνδεση εξοικονομεί πραγματικά χρόνο.
Ξεκινήστε με μια σαφή περίπτωση χρήσης
Πριν από την επιλογή τεχνικών ρυθμίσεων, η επιθυμητή ροή εργασίας θα πρέπει να οριστεί σε καθημερινή γλώσσα. Για παράδειγμα, ένας συντάκτης ανοίγει ένα κείμενο δημοσιευμένης σελίδας, ζητά μια πιο κατανοητή έκδοση και λαμβάνει ένα προσχέδιο στο CMS. Συγκρίνει και τις δύο εκδόσεις, κάνει αλλαγές και μόνο τότε δημοσιεύει. Αυτό το παράδειγμα ονομάζει το περιεχόμενο, την ενεργοποίηση και το αποτέλεσμα.
Οι ασαφείς στόχοι οδηγούν γρήγορα σε μια υπερφορτωμένη ενσωμάτωση. Η δήλωση "Θέλουμε να επεξεργαστούμε όλο το περιεχόμενο μέσω API" αφήνει ανοιχτό το ερώτημα εάν περιλαμβάνονται πλοήγηση, φόρμες, μεταδεδομένα ή παλαιότερα έγγραφα. Μια καλύτερη, πιο συγκεκριμένη ερώτηση είναι: Μπορούμε να μεταφέρουμε το κύριο κείμενο των νέων σελίδων συμβουλών και να επιστρέψουμε το αποτέλεσμα ως μη δημοσιευμένο προσχέδιο; Αυτό μπορεί να απαντηθεί με νόημα.
Τα όρια αποτελούν επίσης μέρος της περίπτωσης χρήσης. Ίσως τα προσωπικά μηνύματα, οι νομικές ειδοποιήσεις ή τα κείμενα που περιέχουν εμπιστευτικά δεδομένα έργου θα πρέπει αρχικά να εξαιρούνται. Τέτοιες αποφάσεις δεν αποτελούν τεχνική αδυναμία. Δημιουργούν ένα διαχειρίσιμο πεδίο εφαρμογής στο οποίο η συντακτική ομάδα και το IT μπορούν να καθορίσουν ποιο περιεχόμενο είναι κατάλληλο και πού χρειάζεται πρόσθετη φροντίδα. Μια σαφής εξαίρεση εμποδίζει μια δοκιμή να γίνει ακούσια γενικής πρόσβασης.
Κατανόηση αιτημάτων και απαντήσεων χωρίς τεχνική ορολογία
Όταν υποβάλλεται ένα αίτημα, το σύστημα στέλνει δεδομένα σε μια καθορισμένη διεύθυνση API. Αυτό περιλαμβάνει το πραγματικό περιεχόμενο και τις πληροφορίες που περιγράφουν την επεξεργασία του. Αυτή θα μπορούσε να είναι η επιθυμητή μορφή γλώσσας, η γλώσσα πηγής ή μια εσωτερική αναφορά. Η τεκμηρίωση του API καθορίζει ποιες πληροφορίες είναι υποχρεωτικές και σε ποια μορφή αναμένονται.
Η απάντηση περιέχει το ζητούμενο αποτέλεσμα ή ένα κατανοητό μήνυμα που εξηγεί γιατί δεν ήταν δυνατή η παράδοσή του. Το CMS πρέπει να διακρίνει μεταξύ αυτών των δύο. Ένα κείμενο που υποβλήθηκε με επιτυχία δεν πρέπει να εκλαμβάνεται ως μήνυμα σφάλματος. Ομοίως, μια κενή απάντηση δεν πρέπει να αποθηκεύεται ως ολοκληρωμένο περιεχόμενο ή ακόμα και να δημοσιεύεται κατά λάθος.
Για την ομάδα περιεχομένου, είναι ιδιαίτερα σημαντικό να γνωρίζει την πηγή ενός αποτελέσματος. Μια μοναδική αναφορά συνδέει την απάντηση με το σωστό κείμενο πηγής. Αυτό αποτρέπει τη σύγχυση όταν επεξεργάζονται ταυτόχρονα πολλές σελίδες. Επιπλέον, θα πρέπει να είναι σαφές ποια έκδοση του πηγαίου κώδικα υποβλήθηκε, ώστε οι μεταγενέστερες αλλαγές να μην αντικατασταθούν απαρατήρητες. Η χρονική σήμανση και η κατάσταση επεξεργασίας βοηθούν στην σωστή κατηγοριοποίηση παλαιότερων απαντήσεων.
Αντιμετωπίστε τα διαπιστευτήρια πρόσβασης σαν κλειδί
Πολλά API απαιτούν ένα μυστικό κλειδί πρόσβασης. Αυτό ενημερώνει την υπηρεσία ποιο σύστημα υποβάλλει ένα αίτημα και ποια δικαιώματα ισχύουν. Αυτό το κλειδί δεν πρέπει να περιλαμβάνεται στο κείμενο της σελίδας, σε ένα στιγμιότυπο οθόνης ή σε δημόσια εκτεθειμένο κώδικα προγράμματος περιήγησης. Εάν ήταν ορατό εκεί, μη εξουσιοδοτημένα άτομα θα μπορούσαν να το αντιγράψουν και να στείλουν αιτήματα στο όνομα της εταιρείας.
Η ασφαλής τοποθεσία βρίσκεται στην πλευρά του διακομιστή σε ένα ειδικό σύστημα διαχείρισης μυστικών. Το κλειδί μπορεί να χρησιμοποιηθεί εκεί χωρίς να μεταδοθεί στους επισκέπτες του ιστότοπου. Διαφορετικά περιβάλλοντα θα πρέπει να έχουν τα δικά τους διαπιστευτήρια πρόσβασης. Αυτό επιτρέπει τον αποκλεισμό ή την ανανέωση της δοκιμαστικής πρόσβασης χωρίς να επηρεάζεται άσκοπα ο ιστότοπος που λειτουργεί.
Τα δικαιώματα θα πρέπει να επιτρέπουν μόνο ό,τι πραγματικά απαιτεί η ενσωμάτωση. Ένα σύστημα που μεταδίδει κείμενο δεν χρειάζεται γενική πρόσβαση διαχειριστή σε άλλους λογαριασμούς ή υπηρεσίες. Εάν ένα κλειδί παραβιαστεί κατά λάθος, πρέπει να είναι ανακλητό και αντικαταστάσιμο. Η σαφής ευθύνη εμποδίζει τα παραβιασμένα διαπιστευτήρια να παραμείνουν ενεργά χωρίς να εντοπιστούν για μεγάλο χρονικό διάστημα. Η τακτική ανανέωση περιορίζει περαιτέρω τις συνέπειες μιας μη εντοπισμένης απώλειας.
Μεταφορά Περιεχομένου με τη Σημασία του
Το κείμενο ιστού σπάνια αποτελείται από μία μόνο μεγάλη παράγραφο. Οι επικεφαλίδες, οι εισαγωγές, οι υποεπικεφαλίδες, το κείμενο συνδέσμων και οι περιγραφές εικόνων εκπληρώνουν διαφορετικές λειτουργίες. Εάν όλα τα πεδία συνδυαστούν χωρίς επισήμανση, το αποτέλεσμα μπορεί να θολώσει αυτούς τους ρόλους. Το αίτημα θα πρέπει επομένως να υποδεικνύει με σαφήνεια ποιο κείμενο ανήκει σε ποιο στοιχείο περιεχομένου και ποια στοιχεία πρέπει να παραμείνουν αμετάβλητα.
Ένα συγκεκριμένο παράδειγμα είναι ένας σύνδεσμος με το κείμενο "Υποβολή αίτησης τώρα". Το ορατό κείμενο μπορεί να υποστεί επεξεργασία, αλλά η διεύθυνση-στόχος δεν πρέπει να χαθεί. Το ίδιο ισχύει και για τις μεταβλητές σε μια επιβεβαίωση ραντεβού, όπως το όνομα ή η ημερομηνία. Οι τεχνικοί δείκτες χρειάζονται προστασία, ενώ το περιβάλλον κείμενο μπορεί να αλλάξει με κατανοητό τρόπο.
Το περιεχόμενο βελτιώνει επίσης το αποτέλεσμα. Η πρόταση "Μπορείτε να το ζητήσετε εδώ" είναι σχεδόν σαφής χωρίς προηγούμενη παράγραφο. Αντί να στέλνει μεμονωμένες προτάσεις, η ενσωμάτωση μπορεί να μεταδώσει ένα λογικά περιορισμένο τμήμα. Ταυτόχρονα, δεν θα πρέπει να στέλνει μια ολόκληρη βάση δεδομένων εάν χρειάζεται μόνο μια παράγραφος. Αυτό διατηρεί το νόημα, τον όγκο δεδομένων και τις απαιτήσεις προστασίας σε μια λογική ισορροπία. Οι επικεφαλίδες συχνά παρέχουν επαρκές περιεχόμενο χωρίς να εκθέτουν πλήρως τις παρακείμενες σελίδες.
Χειρισμός σφαλμάτων με τρόπο που να είναι κατανοητός για τους ανθρώπους
Ένα API μπορεί να μην είναι προσωρινά διαθέσιμο, να απορρίπτει ένα αίτημα ή να χρειάζεται περισσότερο χρόνο από τον αναμενόμενο. Αυτός δεν είναι λόγος για να χάσετε το αρχικό περιεχόμενο. Το CMS θα πρέπει να διατηρεί με ασφάλεια την αρχική έκδοση και να υποδεικνύει ότι δεν υπάρχει ακόμη διαθέσιμο αποτέλεσμα. Μια συντακτική ομάδα χρειάζεται ένα σαφές μήνυμα, όχι απλώς έναν τεχνικό αριθμό χωρίς εξήγηση.
Διαφορετικά σφάλματα απαιτούν διαφορετικές απαντήσεις. Εάν λείπει ένα υποχρεωτικό πεδίο, η επανάληψη της προσπάθειας με τα ίδια δεδομένα συνήθως δεν θα βοηθήσει. Μετά από μια σύντομη διακοπή, μια μεταγενέστερη προσπάθεια μπορεί να αξίζει τον κόπο. Εάν το κλειδί πρόσβασης δεν είναι έγκυρο, πρέπει να ενημερωθεί ο υπεύθυνος τεχνικός. Τα σαφή μηνύματα αποτρέπουν τις ανεπιτυχείς επανάληψης προσπάθειες και την περιττή αβεβαιότητα.
Τα μερικά αποτελέσματα πρέπει επίσης να είναι αναγνωρίσιμα. Εάν έχουν υποβληθεί σε επεξεργασία μόνο εννέα από τις δέκα ενότητες, η σελίδα δεν θα πρέπει να εμφανίζεται ως πλήρης έκδοση. Η ενότητα που λείπει θα πρέπει να παραμένει ορατή και να είναι ξανά επεξεργάσιμη. Για τους συντάκτες, είναι σημαντικό να γνωρίζουν πάντα ποιο περιεχόμενο έχει επιβεβαιωθεί και τι εκκρεμεί ακόμη. Μια χρονική σήμανση από μόνη της δεν αντικαθιστά αυτόν τον σαφή δείκτη κατάστασης.
Επιστροφή αποτελεσμάτων για συντακτική αναθεώρηση
Ένα αποτέλεσμα API θα πρέπει αρχικά να εμφανίζεται ως προσχέδιο εάν το περιεχόμενό του απαιτεί ανθρώπινη έγκριση. Η συντακτική ομάδα πρέπει να είναι σε θέση να συγκρίνει εύκολα την αρχική και την τελική έκδοση. Δεν πρόκειται μόνο για τροποποιημένες λέξεις. Τα ονόματα, οι αριθμοί, οι συνθήκες και οι οδηγίες αξίζουν ιδιαίτερης προσοχής, επειδή ακόμη και οι μικρές αποκλίσεις μπορούν να έχουν σημαντικές συνέπειες.
Το CMS θα πρέπει να επιτρέπει την επεξεργασία χωρίς να αντικαθιστά όλες τις συντακτικές αλλαγές στο επόμενο τεχνικό αίτημα. Η σαφής επισήμανση των εκδόσεων βοηθάει: Τι προήλθε από το API, τι άλλαξε στη συνέχεια και ποια ήταν η αρχική πηγή; Αυτές οι πληροφορίες δίνουν στην ομάδα αυτοπεποίθηση όταν πολλά άτομα εργάζονται στην ίδια σελίδα.
Μια σκόπιμη απόρριψη αποτελεί επίσης μέρος ενός αξιοποιήσιμου αποτελέσματος. Εάν η έκδοση που παραδόθηκε δεν είναι κατάλληλη, η συντακτική ομάδα θα πρέπει να είναι σε θέση να επιμείνει στο υπάρχον κείμενο ή να υποβάλει ένα νέο αίτημα με καλύτερο πλαίσιο. Η ενσωμάτωση είναι χρήσιμη όταν υποστηρίζει τη λήψη αποφάσεων. Δεν θα πρέπει να πιέζει τους ανθρώπους να δημοσιεύσουν μια ακατάλληλη πρόταση. Η απόρριψη δεν θα πρέπει να βλάπτει μια ήδη εγκεκριμένη αρχική έκδοση.
Δοκιμή με πραγματικούς τύπους περιεχομένου στο περιβάλλον δοκιμών
Πριν από την ανάπτυξη της σύνδεσης στον δημόσιο ιστότοπο, θα πρέπει να δοκιμαστεί σε ξεχωριστό περιβάλλον. Αυτό επιτρέπει την εμφάνιση σφαλμάτων χωρίς να επηρεάζονται οι πραγματικές σελίδες. Τα κείμενα δοκιμών θα πρέπει να μοιάζουν πολύ με το πραγματικό περιεχόμενο: σύντομα μηνύματα, μακροσκελείς οδηγοί, σύνδεσμοι, ειδικοί χαρακτήρες και πεδία με μεταβλητές θα αποκαλύψουν διάφορες αδυναμίες μετάδοσης.
Ένα απλό παράδειγμα κειμένου αποδεικνύει μόνο ότι μια απάντηση λαμβάνεται κατ' αρχήν. Το περιεχόμενο με πολλαπλές παραγράφους, ασυνήθιστα μεγάλες λέξεις ή χαρακτήρες από διαφορετικές γλώσσες είναι πιο απαιτητικό. Το κενό κείμενο, τα πολύ μεγάλα εισαγόμενα κείμενα και η ληγμένη πρόσβαση θα πρέπει επίσης να αντιμετωπίζονται κατάλληλα. Αυτό καταδεικνύει πώς συμπεριφέρεται η ενσωμάτωση εκτός του ιδανικού σεναρίου.
Οι συντακτικές δοκιμές συμπληρώνουν την τεχνική αναθεώρηση. Ένας συντάκτης μπορεί να ελέγξει εάν το νέο προσχέδιο εμφανίζεται στην αναμενόμενη θέση και μπορεί εύκολα να συγκριθεί. Μπορεί να εντοπίσει πότε ένα μήνυμα είναι τεχνικά σωστό αλλά ακατανόητο. Η σύνδεση είναι χρησιμοποιήσιμη μόνο όταν τόσο η ανταλλαγή δεδομένων όσο και η καθημερινή δημιουργία περιεχομένου λειτουργούν αξιόπιστα. Ακόμα και οι υποκατάστατες θα πρέπει να είναι σε θέση να αναγνωρίζουν την κατάσταση μιας ανοιχτής επεξεργασίας χωρίς προηγούμενη γνώση.
Επεξεργαστείτε τα δεδομένα με φειδώ και διαφάνεια.
Κάθε αίτημα θα πρέπει να περιέχει μόνο τα δεδομένα που είναι απαραίτητα για το αποτέλεσμά του. Τα ονόματα, οι διευθύνσεις ηλεκτρονικού ταχυδρομείου ή οι εσωτερικές σημειώσεις δεν ανήκουν αυτόματα σε ένα κείμενο απλώς και μόνο επειδή αποθηκεύονται στο ίδιο σύστημα. Πριν από την ενσωμάτωση, θα πρέπει να διευκρινιστεί ποια δεδομένα εγκαταλείπουν την περιοχή ευθύνης του οργανισμού, πού υποβάλλονται σε επεξεργασία και για πόσο χρονικό διάστημα αποθηκεύονται.
Τα αρχεία καταγραφής βοηθούν στην κατανόηση σφαλμάτων, αλλά μπορούν τα ίδια να περιέχουν ευαίσθητες πληροφορίες. Για την αντιμετώπιση προβλημάτων, συχνά επαρκούν μια αναφορά, μια ώρα και ο τύπος του σφάλματος. Το πλήρες περιεχόμενο κειμένου ή τα μυστικά κλειδιά δεν πρέπει να καταγράφονται απρόσεκτα. Η πρόσβαση σε αυτές τις πληροφορίες πρέπει να προστατεύεται εξίσου προσεκτικά με την ίδια τη σύνδεση.
Η διαφάνεια είναι επίσης ζωτικής σημασίας για την εσωτερική συνεργασία. Οι συντακτικές, οι προσωπικές και οι υπηρεσίες πληροφορικής θα πρέπει να έχουν την ίδια κατανόηση για το τι αποστέλλεται και για ποιο σκοπό. Εάν ο τύπος περιεχομένου ή η υπηρεσία αλλάξει αργότερα, αυτή η κατανόηση πρέπει να διατηρηθεί. Μια περιγραφή προϊόντος που κάποτε θεωρούνταν μη κρίσιμη δεν αποτελεί επαρκή βάση για την επεξεργασία εξατομικευμένων επιστολών διαβούλευσης. Τα νέα πεδία στο CMS μπορούν επίσης να εισαγάγουν ακούσια πρόσθετα δεδομένα σε ένα αίτημα.
Μια αξιόπιστη σύνδεση προκύπτει από τη σαφήνεια.
Η επιτυχημένη ενσωμάτωση API δεν ξεκινά με όσο το δυνατόν περισσότερες δυνατότητες. Ξεκινά με μια σαφή περίπτωση περιεχομένου, μια ασφαλή σύνδεση και μια κατανοητή επιστροφή στο CMS. Όταν τα τμήματα σύνταξης και πληροφορικής μπορούν να περιγράψουν την ίδια διαδικασία, οι τεχνικές αποφάσεις είναι ευκολότερο να εξεταστούν και τα προβλήματα μπορούν να αποδοθούν πιο γρήγορα στο σωστό τμήμα.
Στην καθημερινή πρακτική, οι αξιόπιστες μεταβάσεις είναι ύψιστης σημασίας. Αποστέλλεται το σωστό περιεχόμενο, η δομή του παραμένει αναγνωρίσιμη, τα σφάλματα δεν θέτουν σε κίνδυνο την πηγή και το αποτέλεσμα φτάνει ως επαληθεύσιμη έκδοση στην αναμενόμενη τοποθεσία. Τα δεδομένα πρόσβασης και οι ευαίσθητες πληροφορίες παραμένουν προστατευμένες. Αυτές οι ιδιότητες μετατρέπουν ένα λειτουργικό αίτημα σε ένα χρήσιμο εργαλείο για τη δημιουργία περιεχομένου. Διευκολύνουν επίσης την αντιμετώπιση προβλημάτων εάν μια υπηρεσία ή περιεχόμενο αλλάξει αργότερα.
Μόνο τότε έχει νόημα η επέκταση σε άλλους τύπους σελίδων ή μεγαλύτερους όγκους. Κάθε νέο κομμάτι περιεχομένου μπορεί να φέρει διαφορετικά πεδία, κινδύνους και συντακτικά ερωτήματα. Ένας αποδεδειγμένος πυρήνας διευκολύνει αυτήν την επέκταση χωρίς να μεταφέρει τυφλά παλιές υποθέσεις. Αυτό διατηρεί την ενσωμάτωση κατανοητή, ελεγχόμενη και επικεντρωμένη στο πραγματικό όφελος για τους αναγνώστες. Η αυξανόμενη χρήση εξακολουθεί να απαιτεί την ίδια ανιχνεύσιμη σύνδεση μεταξύ πηγής και αποτελέσματος.