Μετάβαση στη διεύθυνση του API

Οι παλαιότερες ενσωματώσεις καλούν το API στην κύρια διεύθυνση της Sursa, αυτή που ανοίγουν οι χρήστες στο πρόγραμμα περιήγησης, για παράδειγμα https://app.sursa.com/v1/…. Πλέον το API έχει και τη δική του διεύθυνση, https://api.sursa.com στο cloud ή https://api.<your domain> στην εγκατάστασή σας. Έχει σχεδιαστεί για ενσωματώσεις: κλιμακώνεται οριζόντια πίσω από έναν εξισορροπητή φορτίου και δεν εξυπηρετεί τίποτε άλλο εκτός από το API.

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

Τι μένει ίδιο

Οι διαδρομές, οι παράμετροι, τα πεδία, οι κωδικοί σφάλματος και τα συμβάντα: το GET /v1/cards είναι το ίδιο αίτημα και στις δύο διευθύνσεις.
Τα κλειδιά API. Τα ίδια κλειδιά kb_ και kbsrc_ λειτουργούν και στις δύο διευθύνσεις, με τον ίδιο ρόλο, τις ίδιες εμβέλειες και το ίδιο προφίλ δεδομένων.
Τα κλειδιά ταυτοδυναμίας, τα όρια ρυθμού και οι ποσοστώσεις. Τα αιτήματα και στις δύο διευθύνσεις μετρούν στις ίδιες ποσοστώσεις του οργανισμού.
Τα webhooks. Οι παραδόσεις, οι υπογραφές και τα μυστικά δεν εξαρτώνται από τη διεύθυνση που καλείτε.
Οι σύνδεσμοι στις αποκρίσεις. Το doc_url ενός σφάλματος παραπέμπει σε αυτή την πύλη και η κεφαλίδα Link μιας σελίδας λίστας παραπέμπει στη διεύθυνση του API, όποια διεύθυνση κι αν καλείτε.

Τι διαφέρει στη διεύθυνση του API

Στην κύρια διεύθυνση	Στη διεύθυνση του API
Κάθε τελικό σημείο της εφαρμογής ιστού, μαζί με τα εσωτερικά	Μόνο τα τελικά σημεία της δημόσιας αναφοράς API. Κάθε άλλη διαδρομή απαντά `404` με τον κωδικό `api.not_found`.
Ένα κλειδί στο `X-API-Key` ή στο `Authorization` ή ένα cookie συνεδρίας του προγράμματος περιήγησης	Ένα κλειδί ή ένα διακριτικό πρόσβασης OAuth, κατά προτίμηση στο `Authorization: Bearer`. Τα cookies αγνοούνται.
`GET /auth/me`	`GET /v1/me`. Οι διαδρομές κάτω από το `/auth/` δεν εξυπηρετούνται.
Η λειτουργία «View as» (προβολή από τη σκοπιά άλλου χρήστη) μέσω cookie	Η κεφαλίδα `X-View-As`, για κλειδιά με τον ρόλο `admin`.
Ένας διακομιστής ή ένα σταθερό σύνολο διακομιστών	Πολλοί διακομιστές πίσω από έναν εξισορροπητή φορτίου.

Η τελευταία γραμμή έχει σημασία μόνο σε μία περίπτωση: μια απάντηση σε ροή του POST /v1/chat. Μια ροή που διακόπηκε συνεχίζει από το Last-Event-ID μόνο στον διακομιστή που γράφει την απάντηση. Αν η ενσωμάτωσή σας συνεχίζει ροές, δώστε σε κάθε ερώτηση ένα request_id, ώστε μια επανάληψη σε άλλον διακομιστή να λάβει την αποθηκευμένη απάντηση αντί για δεύτερη. Δείτε την ενότητα Συνέχιση ροής που διακόπηκε.

Πριν από τη μετάβαση

Ελέγξτε ότι κάθε κλήση είναι δημόσια. Καταγράψτε τις διαδρομές που καλεί η ενσωμάτωσή σας και αναζητήστε την καθεμία στην αναφορά API ή συγκρίνετέ τις με την προδιαγραφή της νέας διεύθυνσης:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

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

Ελέγξτε πώς γίνεται ο έλεγχος ταυτότητας. Αν η ενσωμάτωση συνδέεται με τον κωδικό πρόσβασης ενός χρήστη και ένα cookie συνεδρίας, μεταφέρετέ την πρώτα σε ένα κλειδί API. Αν στέλνει X-API-Key, η μετάβαση στο Authorization: Bearer συνιστάται, αλλά δεν είναι υποχρεωτική.

Ελέγξτε το δίκτυό σας. Επιτρέψτε την εξερχόμενη σύνδεση HTTPS προς το νέο όνομα κεντρικού υπολογιστή στο τείχος προστασίας και στους διακομιστές μεσολάβησης.

Μετάβαση βήμα προς βήμα

Κάντε τη βασική διεύθυνση URL ρύθμιση της ενσωμάτωσής σας, αν δεν είναι ήδη.
Δοκιμάστε τη νέα διεύθυνση με ένα αίτημα ανάγνωσης:
```
curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"
```
Εκτελέστε τις δοκιμές της ενσωμάτωσής σας στη νέα διεύθυνση, με ένα δοκιμαστικό κλειδί και μια δοκιμαστική συλλογή.
Μεταφέρετε ένα μέρος της κίνησης, για παράδειγμα μία διεργασία ή ένα περιβάλλον, και παρακολουθήστε για 404 api.not_found, 401 και 5xx στα αρχεία καταγραφής σας. Κάθε απόκριση φέρει X-Request-Id· κρατήστε το μαζί με τα αρχεία καταγραφής σας.
Μεταφέρετε την υπόλοιπη κίνηση. Κρατήστε την παλιά βασική διεύθυνση URL στις ρυθμίσεις σας για λίγο, ώστε να μπορείτε να επιστρέψετε σε δευτερόλεπτα.

Τι να ελέγξετε μετά τη μετάβαση

Το GET /v1/health στη νέα διεύθυνση επιστρέφει την ίδια version με την παλιά.
Οι κεφαλίδες RateLimit υπάρχουν στις αποκρίσεις. Αν η ενσωμάτωσή σας επιβραδύνεται μόνη της με βάση τις X-RateLimit-*, μπορεί να συνεχίσει να το κάνει: στέλνονται και τα δύο σύνολα. Δείτε τον οδηγό Όρια ρυθμού και ποσοστώσεις.
Αν η ενσωμάτωσή σας εκτελείται σε πρόγραμμα περιήγησης, δεν χρειάζεται πια δικό σας διακομιστή μεσολάβησης για το CORS: η διεύθυνση του API επιτρέπει αιτήματα από οποιοδήποτε origin, χωρίς cookies.