Πώς λειτουργεί το API του Optifora
Η σελίδα αυτή περιγράφει τη μορφή του API: πώς αποδεικνύεται η ταυτότητα, πώς προχωρούν οι εκδόσεις, εντός ποιων ορίων παραμένει ένα αίτημα, πώς μοιάζει ένα σφάλμα και πώς ανταλλάσσονται δεδομένα με τον έξω κόσμο.
Το προϊόν βρίσκεται υπό ανάπτυξη και η επιφάνεια του API συμπληρώνεται ακόμη. Ένα έγγραφο αναφοράς για τα άκρα θα δημοσιευτεί χωριστά· η σελίδα αυτή δεν περιέχει ούτε διεύθυνση ούτε δείγμα κλήσης, μόνο τον μηχανισμό.
Έλεγχος ταυτότητας
Κάθε αίτημα ανήκει είτε σε ένα πρόσωπο είτε σε μια καταχωρισμένη εφαρμογή. Αίτημα χωρίς ταυτότητα που φτάνει σε προστατευμένο άκρο επιστρέφει ως μη πιστοποιημένο.
- Διακριτικό τύπου BearerΤο διακριτικό πρόσβασης ταξιδεύει στην κεφαλίδα εξουσιοδότησης του αιτήματος. Είναι υπογεγραμμένο και δηλώνει μόνο σε ποιον ανήκει το αίτημα.
- Σύντομη διάρκεια ζωήςΤο διακριτικό πρόσβασης λήγει μετά από διάστημα που μετριέται σε λεπτά· η διάρκεια είναι ρύθμιση της εγκατάστασης και εξ ορισμού είναι τριάντα λεπτά.
- Ανανέωση και εναλλαγήΗ συνεδρία παρατείνεται με διακριτικό ανανέωσης και κάθε παράταση εκδίδει νέο ζεύγος. Αν ένα ήδη χρησιμοποιημένο διακριτικό ανανέωσης παρουσιαστεί δεύτερη φορά, ανακαλούνται όλες οι συνεδρίες του συγκεκριμένου προσώπου.
- Τα δικαιώματα δεν ενσωματώνονται στο διακριτικόΤο διακριτικό φέρει μόνο ταυτότητα· το τι επιτρέπεται να δει κάποιος ζητείται από τη βάση δεδομένων σε κάθε αίτημα. Έτσι, ένα δικαίωμα που ανακαλείται παύει να ισχύει πριν λήξει το διακριτικό που ήδη κρατά ο χρήστης.
- Κλειδί ενσωματωτήΚάθε καταχωρισμένη εφαρμογή συνδέεται με το δικό της κλειδί. Η καθαρή τιμή εμφανίζεται μία μόνο φορά, κατά τη δημιουργία· αποθηκεύεται η σύνοψή της και το μη απόρρητο πρόθεμα που επιτρέπει την αναγνώριση του κλειδιού.
- Η πρόσβαση εκχωρείται από τον οργανισμόΌσο ευρέως και αν χρησιμοποιείται μια εφαρμογή, χωρίς εκχώρηση καταγεγραμμένη από τον οργανισμό δεν βλέπει ούτε μία εγγραφή. Η εκχώρηση φέρει ημερομηνία, έχει καθορισμένο εύρος και ανακαλείται.
Διαχείριση εκδόσεων
- Η έκδοση βρίσκεται μέσα στη διαδρομήΤα άκρα δημοσιεύονται πίσω από ένα πρόθεμα έκδοσης· η σημερινή επιφάνεια είναι η έκδοση ένα.
- Μια ασύμβατη αλλαγή ανοίγει νέα διαδρομήΤο συμβόλαιο ενός υπάρχοντος άκρου δεν σπάει επιτόπου. Μια μη συμβατή αλλαγή δημοσιεύεται σε νέα διαδρομή έκδοσης, ενώ η παλιά συνεχίζει να λειτουργεί.
- Το έγγραφο δηλώνει τη δική του έκδοσηΗ αναφορά φέρει τον αριθμό έκδοσης από τον οποίο παράχθηκε· ποια έκδοση διαβάζετε την απαντά το ίδιο το έγγραφο.
Περιβάλλοντα και όρια
Η αναφορά δηλώνει δύο περιβάλλοντα: παραγωγή και τοπική ανάπτυξη. Η ριζική διεύθυνση παραδίδεται στον ενσωματωτή μαζί με το κλειδί του· δεν δημοσιεύεται σε αυτή τη σελίδα.
- Η ζωντάνια και η ετοιμότητα μετρώνται χωριστάΈνα άκρο δηλώνει ότι η διεργασία είναι ενεργή· το δεύτερο στέλνει πραγματικό ερώτημα στη βάση δεδομένων και επιβεβαιώνει ότι είναι προσβάσιμη. Μόνο το δεύτερο κρίνει αν πρέπει να σταλεί κίνηση.
- Οι προελεύσεις του προγράμματος περιήγησης περιορίζονται σε λίσταΑιτήματα από άλλη προέλευση γίνονται δεκτά μόνο από προελεύσεις που έχουν δηλωθεί εκ των προτέρων· όσο η λίστα είναι κενή, ένα αίτημα προγράμματος περιήγησης από άλλη προέλευση απορρίπτεται.
- Όριο σώματοςΤο σώμα ενός αιτήματος δεν μπορεί να υπερβαίνει τα πέντε megabyte. Τα μεγάλα σύνολα ταξιδεύουν ως εργασία μαζικής μεταφοράς με δική της εγγραφή κατάστασης, όχι ως ένα ενιαίο αίτημα.
- Τα απόρρητα δεν γράφονται στο αρχείο καταγραφήςΤο αρχείο καταγραφής του διακομιστή δεν κρατά κεφαλίδα εξουσιοδότησης, ούτε cookie, ούτε κωδικό πρόσβασης, ούτε αριθμό ταυτότητας.
Όριο ρυθμού
Το όριο ισχύει ανά διεύθυνση και ανά λεπτό. Η προεπιλογή είναι 120 αιτήματα το λεπτό και ορίζεται κατά την εγκατάσταση. Το υπόλοιπο αναφέρεται σε κεφαλίδες σε κάθε απόκριση.
| Κεφαλίδα απόκρισης | Τι δηλώνει |
|---|---|
| x-ratelimit-limit | Το συνολικό όριο εντός του παραθύρου. |
| x-ratelimit-remaining | Τι απομένει σε αυτό το χρονικό παράθυρο. |
| x-ratelimit-reset | Δευτερόλεπτα μέχρι να ανανεωθεί το όριο. |
| retry-after | Πόσα δευτερόλεπτα πριν από νέα προσπάθεια. Υπάρχει μόνο στην απόκριση που απέρριψε το αίτημα. |
Μόλις ξεπεραστεί το όριο, το αίτημα απορρίπτεται και η απόκριση δηλώνει πόσα δευτερόλεπτα πρέπει να περιμένετε. Η επανάληψη γίνεται μετά από αυτόν τον χρόνο, όχι αμέσως.
Μορφή σφάλματος
Κάθε σφάλμα επιστρέφει με τον ίδιο φάκελο: ένα σύντομο πεδίο κωδικού για να διακλαδωθεί η μηχανή και ένα πεδίο επεξήγησης για να το διαβάσει ένας άνθρωπος.
- errorΟ σύντομος κωδικός βάσει του οποίου αποφασίζει ο πελάτης.
- messageΗ επεξήγηση του τι συνέβη.
| Κατάσταση | Πεδίο κωδικού | Τι σημαίνει |
|---|---|---|
| 400 | Bad Request | Το αίτημα δεν ταιριάζει με το σχήμα. Η επεξήγηση κατονομάζει το πεδίο που λείπει ή είναι άκυρο. |
| 401 | unauthenticated | Δεν υπάρχει έγκυρη ταυτότητα: δεν στάλθηκε διακριτικό, έχει λήξει ή δεν επαληθεύτηκε. |
| 404 | Not Found | Δεν υπάρχει τέτοιο άκρο ή δεν υπάρχει τέτοια εγγραφή. |
| 429 | Too Many Requests | Το όριο ρυθμού ξεπεράστηκε· η απόκριση δηλώνει πόσο πρέπει να περιμένετε. |
| 5xx | internal_error | Απροσδόκητη αστοχία. Η λεπτομέρεια δεν παραδίδεται στον πελάτη· καταγράφεται στο αρχείο καταγραφής του διακομιστή. |
Σελιδοποίηση
Τα άκρα που επιστρέφουν λίστες δέχονται τις ίδιες δύο παραμέτρους και επιστρέφουν τους ίδιους μετρητές, ώστε ένας πελάτης σελιδοποίησης να μην ξαναγράφεται για κάθε άκρο.
- limitΠόσες εγγραφές πρέπει να περιέχει μια σελίδα. Τουλάχιστον μία, το πολύ διακόσιες· πενήντα όταν δεν ορίζεται.
- offsetΠόσες εγγραφές θα παραλειφθούν. Ξεκινά από το μηδέν.
- totalΠόσες εγγραφές ταιριάζουν συνολικά με τα φίλτρα.
- countΠόσες εγγραφές φέρει πραγματικά αυτή η απόκριση.
Η απόκριση επαναλαμβάνει επίσης το limit και το offset που χρησιμοποίησε· ο πελάτης διαβάζει τη θέση του από την απάντηση αντί να τη μαντεύει.
Ανταλλαγή δεδομένων και webhook
Ο τρόπος ανταλλαγής είναι ρύθμιση, όχι ξεχωριστό προϊόν: κάθε καταχωρισμένη εφαρμογή φέρει στη δική της εγγραφή τον τρόπο με τον οποίο λειτουργεί.
| Τρόπος | Τι σημαίνει |
|---|---|
| Μονόδρομη — προς τα έξω | Το Optifora δημοσιεύει δεδομένα· η άλλη πλευρά τα διαβάζει ή εγγράφεται σε συμβάντα. |
| Μονόδρομη — προς τα μέσα | Η άλλη πλευρά προωθεί δεδομένα· το Optifora τα επικυρώνει και τα καταγράφει. |
| Αμφίδρομη | Και οι δύο πλευρές γράφουν· ο κανόνας επίλυσης συγκρούσεων ορίζεται εκ των προτέρων. |
| Χειραψία | Κάθε μεταφορά ανοίγει μια συνεδρία: πρόταση, επαλήθευση, έγκριση, μεταφορά και απόδειξη. Η απόδειξη μένει και στις δύο πλευρές. |
- Τα συμβάντα προωθούνται προς τα έξωΈνα webhook στέλνει το συμβάν στη διεύθυνση επανάκλησης που δήλωσε η καταχωρισμένη εφαρμογή. Συμβάν που δεν μπορεί να παραδοθεί παραμένει στην ουρά και επαναλαμβάνεται· δεν απορρίπτεται ποτέ σιωπηλά.
- Το ίδιο αίτημα δεν γράφει δύο φορέςΈνα αίτημα εγγραφής φέρει κλειδί μοναδικότητας. Ένα δεύτερο αίτημα με το ίδιο κλειδί δεν δημιουργεί δεύτερη εγγραφή.
- Κάθε κλήση μετριέταιΠοιος κάλεσε, πότε, με ποιο εύρος και με ποιο αποτέλεσμα — όλα καταγράφονται. Η ίδια εγγραφή απαντά τόσο στην αποσφαλμάτωση όσο και στο ερώτημα ποιος άντλησε αυτά τα δεδομένα.
- Οι δικές μας εφαρμογές χρησιμοποιούν την ίδια πόρταΔεν υπάρχει προνομιακή δεύτερη διαδρομή. Η δική μας ενσωμάτωση είναι η απόδειξη της επιφάνειας που συναντά ένας εξωτερικός προγραμματιστής.
Το μοντέλο δεδομένων για το στρώμα ανταλλαγής υπάρχει· τα άκρα του δεν έχουν δημοσιευτεί ακόμη. Όταν δημοσιευτούν, η ενότητα αυτή θα παραπέμπει στις καταχωρίσεις τους στην αναφορά.
Έγγραφα αναφοράς
Η αναφορά δεν γράφεται με το χέρι· παράγεται από τα σχήματα των άκρων. Καθώς κάθε άκρο παραδίδει το σχήμα του, το έγγραφο συμπληρώνεται από μόνο του, ώστε το έγγραφο και η συμπεριφορά να μην μπορούν να αποκλίνουν.
- Σήμερα: υπό προετοιμασίαΤα σχήματα μεταφέρονται ενότητα προς ενότητα. Πριν δημοσιευτεί το έγγραφο, το αίτημα και η απόκριση κάθε άκρου θα είναι ορατά μέσα σε αυτό.
- Θα δημοσιευτούν δύο μορφέςΈνα έγγραφο OpenAPI αναγνώσιμο από μηχανή και μια σελίδα αναφοράς που παράγεται από το ίδιο έγγραφο και μπορεί να διαβαστεί σε πρόγραμμα περιήγησης.
- Η πρόσβαση είναι κλιμακωτήΗ επισκόπηση είναι ανοιχτή σε όλους. Η πλήρης αναφορά ενδέχεται να βρίσκεται πίσω από ένα διακριτικό τεκμηρίωσης που δίνεται σε καταχωρισμένο ενσωματωτή· τα κλειδιά παραγωγής και οι διευθύνσεις επανάκλησης δεν αποτελούν καθόλου ζήτημα τεκμηρίωσης — ανήκουν στην εγγραφή της εφαρμογής.
- Πρότυπο διευθύνσεωνΔημοσιεύονται δύο αναφορές και οι διευθύνσεις τους είναι σταθερές: το client-api.optifora.com/docs είναι ανοιχτό, το admin-api.optifora.com/docs απαιτεί εξουσιοδότηση και είναι κλειστό προς τα έξω. Κανένα από τα δύο δεν είναι ενεργό σήμερα· οι σύνδεσμοι θα προστεθούν σε αυτή την ενότητα μόλις γίνουν.
Αν το σχέδιο ενσωμάτωσής σας είναι ήδη σαφές, γράψτε μας από τη σελίδα επικοινωνίας: θα είστε από τους πρώτους που θα ενημερωθούν όταν ανοίξει η επιφάνεια.
Έχετε συγκεκριμένο αίτημα;
Οι σελίδες αυτές εξηγούν πώς λειτουργεί η διαδικασία υποστήριξης. Αν έχετε αίτημα ή ερώτηση, γράψτε μας από τη σελίδα επικοινωνίας.
Μεταβείτε στη σελίδα επικοινωνίας