17. API ενσωμάτωσης και κλειδιά API

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

Ποιος μπορεί να αποκτήσει κλειδί API

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

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

Δημιουργία κλειδιού

Στην κάρτα Κλειδιά API της σελίδας Προφίλ κάνε κλικ στο κουμπί Νέο κλειδί.
Δώσε ένα όνομα στο κλειδί (για παράδειγμα το όνομα του προγράμματος που θα το χρησιμοποιεί).
Επίλεξε το εύρος: το Ανάγνωση έργων δίνει τη λίστα έργων και τα δεδομένα τους, το Ανάγνωση εγγράφων δίνει τους καταλόγους, την επιμέτρηση και το πακέτο σχεδίων. Όρισε μόνο ό,τι χρειάζεται πραγματικά το πρόγραμμα.
Επίλεξε τη λήξη: 30, 90 ή 365 ημέρες. Ένα κλειδί που έχει λήξει σταματά να λειτουργεί· στη θέση του δημιουργείς νέο.
Δώσε τον τρέχοντα κωδικό σου (σε λογαριασμό χωρίς κωδικό απαιτείται πρόσφατη σύνδεση). Για το πρώτο κλειδί αποδέξου τους όρους χρήσης του API.

Μετά τη δημιουργία το κλειδί εμφανίζεται μία και μόνο φορά: αντίγραψέ το και φύλαξέ το σε ασφαλές μέρος. Αργότερα στη λίστα φαίνεται μόνο το πρόθεμά του (avk_…), με τις ημερομηνίες δημιουργίας και λήξης, την τελευταία χρήση και τον αριθμό κλήσεων. Για το νέο κλειδί στέλνουμε επίσης ειδοποίηση με e-mail (χωρίς το ίδιο το κλειδί).

Ανάκληση κλειδιού

Με το κουμπί Ανάκληση δίπλα στο κλειδί στην κάρτα, το κλειδί γίνεται αμέσως άχρηστο· αυτό δεν αναιρείται. Ανάκλησε το κλειδί όταν δεν το χρησιμοποιείς πια, όταν καταργείς το πρόγραμμα που το χρησιμοποιούσε ή αν υποψιάζεσαι ότι διέρρευσε.

Συμβουλές ασφαλείας

Αντιμετώπισε το κλειδί όπως τον κωδικό σου: όποιος το γνωρίζει μπορεί να διαβάσει τα έργα σου εντός του ορισμένου εύρους.
Φύλαξέ το σε χώρο αποθήκευσης μυστικών (διαχειριστής κωδικών, μεταβλητή περιβάλλοντος του διακομιστή ή μυστική μεταβλητή του CI), όχι στον πηγαίο κώδικα: να μην μπει στο αποθετήριο git, σε κοινόχρηστο υπολογιστικό φύλλο ή σε e-mail.
Μην το χρησιμοποιείς σε κώδικα που εκτελείται στον περιηγητή (ιστοσελίδα, επέκταση περιηγητή): εκεί μπορεί να το διαβάσει οποιοσδήποτε. Η θέση του κλειδιού είναι σε διακομιστή, σε script ή σε πρόγραμμα επιφάνειας εργασίας.
Κάθε πρόγραμμα να έχει δικό του κλειδί, με το στενότερο δυνατό εύρος και σύντομη λήξη· έτσι η ανάκληση ενός κλειδιού δεν σταματά κάτι άλλο.

Χρήση από πρόγραμμα

Στην κεφαλίδα του αιτήματος το κλειδί αποστέλλεται ως Bearer token: Authorization: Bearer avk_…. Τα endpoints βρίσκονται κάτω από το /api/v1/ (για παράδειγμα GET /api/v1/projects) και απαντούν σε JSON. Η πλήρης περιγραφή σε μορφή OpenAPI είναι διαθέσιμη στη διεύθυνση /api/v1/openapi.json· τα περισσότερα εργαλεία ανάπτυξης μπορούν να την εισαγάγουν.

Ο αριθμός των κλήσεων περιορίζεται ανά κλειδί και ανά λογαριασμό (από προεπιλογή 60 ανά λεπτό και 10.000 ανά ημέρα)· σε περίπτωση υπέρβασης ο διακομιστής απαντά με 429, οπότε περίμενε λίγο. Η σύνδεση στον ιστότοπο (cookie) δεν ανοίγει το API, και το κλειδί δεν σε συνδέει στη διεπαφή ιστού.