Διεύθυνση του API και περιβάλλοντα

Το API της Sursa έχει τη δική του διεύθυνση, ξεχωριστή από τη διεύθυνση με την οποία οι χρήστες ανοίγουν τη Sursa στο πρόγραμμα περιήγησης. Όλες οι διαδρομές ξεκινούν με /v1.

Πού λειτουργεί η Sursa	Διεύθυνση του API	Αυτή η πύλη
Cloud της Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Η δική σας εγκατάσταση	`https://api.<your domain>`, όπως την έχει ρυθμίσει ο διαχειριστής σας	`/developers/` στη διεύθυνση του API
Η εγκατάστασή σας χωρίς ξεχωριστή διεύθυνση API	η κύρια διεύθυνση της εγκατάστασης	`/developers/` στην κύρια διεύθυνση

Η διεύθυνση του API εξυπηρετεί μόνο το API: δεν υπάρχει σε αυτήν σελίδα σύνδεσης, cookies ούτε περιβάλλον ιστού. Κάθε αίτημα πιστοποιείται με ένα κλειδί API ή ένα διακριτικό πρόσβασης OAuth. Τη διεύθυνση μπορεί να την εξυπηρετούν πολλοί διακομιστές πίσω από έναν εξισορροπητή φορτίου· η ενσωμάτωσή σας δεν χρειάζεται να ξέρει πόσοι είναι.

Οι ενσωματώσεις που καλούν το API στην κύρια διεύθυνση (για παράδειγμα https://app.sursa.com/v1) συνεχίζουν να λειτουργούν. Δείτε τον οδηγό Μετάβαση στη διεύθυνση του API για τις λίγες διαφορές και μια μετάβαση βήμα προς βήμα.

Βασική διεύθυνση URL

Σχηματίζετε κάθε αίτημα από μία βασική διεύθυνση URL στις ρυθμίσεις σας, ώστε ο ίδιος κώδικας να εκτελείται σε οποιοδήποτε περιβάλλον:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Χρησιμοποιείτε μόνο HTTPS και κρατάτε το κλειδί έξω από τα αρχεία καταγραφής των αιτημάτων σας.

Έκδοση και προδιαγραφή

Το GET /v1/health δείχνει αν η διεύθυνση λειτουργεί και επιστρέφει την έκδοση της Sursa που την εξυπηρετεί. Απαντά χωρίς κλειδί, οπότε μπορείτε να το χρησιμοποιήσετε στην παρακολούθηση:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Αυτή είναι η έκδοση της κυκλοφορίας της Sursa, όχι του API. Η έκδοση του API είναι το info.version της προδιαγραφής του. Η προδιαγραφή OpenAPI 3.1 του API δημοσιεύεται στην ίδια διεύθυνση, χωρίς έλεγχο ταυτότητας:

Διαδρομή	Περιεχόμενο
`GET /openapi.json`	Η δημόσια προδιαγραφή, με αυτή τη διεύθυνση στο `servers`.
`GET /v1/openapi-public.json`	Η ίδια προδιαγραφή. Υποστηρίζει `ETag` και `If-None-Match`.

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

Δοκιμές

Η Sursa δεν έχει ξεχωριστή λειτουργία δοκιμών: κάθε αίτημα με κλειδί επηρεάζει τα πραγματικά δεδομένα του οργανισμού του. Για να αναπτύσσετε και να δοκιμάζετε με ασφάλεια:

Δημιουργήστε ένα ξεχωριστό κλειδί για την ανάπτυξη με τον στενότερο ρόλο και τις εμβέλειες που χρειάζεται η εργασία.
Γράφετε σε μια ξεχωριστή συλλογή, για παράδειγμα sandbox, που τη βλέπει μόνο η ομάδα σας, και διαγράψτε την όταν τελειώσετε.
Αν η εταιρεία σας έχει ξεχωριστό οργανισμό ή ξεχωριστή εγκατάσταση της Sursa για δοκιμές, στρέψτε τη βασική διεύθυνση URL και το κλειδί εκεί. Τίποτε άλλο στον κώδικά σας δεν αλλάζει.
Κάντε τις επαναλήψεις ασφαλείς από την αρχή: στέλνετε ένα Idempotency-Key με κάθε POST και PATCH.

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

Απαιτήσεις δικτύου

Εξερχόμενη σύνδεση HTTPS (θύρα 443) από τους διακομιστές σας προς τη διεύθυνση του API.
Στους κανόνες του τείχους προστασίας επιτρέψτε το όνομα κεντρικού υπολογιστή αντί για σταθερές διευθύνσεις IP, όπου το δίκτυό σας το επιτρέπει: οι διακομιστές πίσω από τη διεύθυνση μπορεί να αλλάξουν, καθώς προστίθεται χωρητικότητα.
Οι εφαρμογές προγράμματος περιήγησης μπορούν να καλούν το API απευθείας: οι αποκρίσεις επιτρέπουν οποιοδήποτε origin (Access-Control-Allow-Origin: *) χωρίς cookies. Λάβετε υπόψη ότι ένα κλειδί που χρησιμοποιείται σε πρόγραμμα περιήγησης είναι ορατό στον χρήστη αυτού του προγράμματος περιήγησης.