API (Application Programming Interface)

Το Bim παρέχει τους ακόλουθους τρόπους πρόσβασης και χρήσης των δεδομένων του, από εφαρμογές τρίτων (πχ: Excel, Word, Databases, Mobile APPs, κλπ):

  1. Backup    (ACP » Loops » Database Backup)
  2. Export    (σχετική επιλογή στο μενού τίτλου των πινάκων)
  3. Προβολές  (σχετικό μενού στο ERP), και
  4. API       το οποίο εξετάζουμε εδώ

Η χρήση του API έχει δύο σημαντικές διαφορές σε σχέση με τις υπόλοιπες μεθόδους: είναι online και read/write. Το χαρακτηριστικό online σημαίνει πως τα δεδομένα που παίρνετε μέσω του API είναι "φρέσκα" σε αντίθεση με αυτά των άλλων μεθόδων, τα οποία πρέπει πρώτα να εξάγετε (σε κάποια μορφή) και στη συνέχεια να εισάγετε στην εφαρμογή σας. Το χαρακτηριστικό read/write σημαίνει πως το API σας δίνει τη δυνατότητα ταυτόχρονης ανάγνωσης και εγγραφής της βάσης δεδομένων. Εκτός του API, άλλοι τρόποι ενημέρωσης της βάσης είναι οι εργασίες "Table Import" και "Table Update", του μενού "Loops" στο ACP.

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

Ενεργοποίηση και πρόσβαση

Η υπηρεσία είναι εξορισμού ανενεργή. Την ενεργοποιείτε με την ακόλουθη ρύθμιση:

ACP » Settings » Authority » HTTP » Enable API Access

Το URL της υπηρεσίας είναι:

https://domain.bimol.gr/api/

Το authorization γίνεται με 2 τρόπους, ανάλογα με την εφαρμογή ή client που θα χρησιμοποιηθεί:

  1. Interactive Login
    Αν η εφαρμογή σας είναι interactive και υποστηρίζει cookies, τότε μπορείτε να κάνετε χρήση του Bim login, το οποίο θυμίζουμε πως είναι κοινό για όλες τις εφαρμογές του συστήματος (SSO).
  2. API Token
    Αν η εφαρμογή σας δεν είναι interactive, τότε θα χρειαστείτε ένα token, το οποίο δημιουργείται από τον Διαχειριστή, και δηλώνεται ως "X-API-TOKEN" request header.

API Token

Η δημιουργία και χρήση του API Token γίνεται ως ακολούθως:

  1. Ο client κάνει μία σύνδεση στο auth endpoint:
    https://domain.bimol.gr/api/auth/
    ...για να λάβει το ακόλουθο response:
    {"status":403,"result":"Forbidden","meta":null}
  2. Ανοίγετε το αρχείο "ACP ▶ Database ▶ Session", κάνετε κλικ στη συνεδρία του client, και στο εικονίδιο του πεδίου "API Token". Συμπληρώνετε τα πεδία και ενημερώνετε τις δύο φόρμες.
  3. Ο client επαναλαμβάνει την ίδια κλήση, που όμως αυτήν τη φορά έχει διαφορετικό response:
    {"status":200,"result":{"header":"X-API-TOKEN","value":"96tQq2Wxdi...2GjMEd2zQg"},"meta":null}

Από δω και πέρα, και μέχρι να λήξει η συνεδρία του, ο client μπορεί να εκτελεί API requests, αρκεί να περιλαμβάνουν το ζητούμενο header.

Αρχιτεκτονική και πρωτόκολλο

Το API είναι δομημένο σύμφωνα με την αρχιτεκτονική REST. Το format που χρησιμοποιείται είναι JSON, τα δε responses έχουν τα ακόλουθα keys:

  1. status
    Ισότιμο με το HTTP response status code. Περιλαμβάνεται χάριν ευκολίας.
  2. result
    Το ζητούμενο resource ή κάποιο μήνυμα λάθους.
  3. meta
    Πληροφορίες σχετικές με το "result".

Το API είναι self discoverable, με την έννοια του ότι σε κάθε node του URL path, μέχρι αυτό να καταλήξει σε resource (endpoint), αντί σφάλματος επιστρέφονται οι πιθανές τιμές του επόμενου node.

Παραδείγματα

Μια κλήση στο root του API, μας επιστρέφει τα διαθέσιμα methods:

/api/

{
"status": 200,
"result": ["auth","crud"],
"meta"  : null
}

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

/api/crud/

{
"status": 200,
"result": ["article","banner",...,"upload","user"],
"meta"  : null
}

Συνεχίζοντας την εξερεύνηση μας, ζητάμε πληροφορίες για κάποιο από τα αρχεία του προηγούμενου βήματος:

/api/crud/people/

{
"status": 200,
"result": 
    [
    "{ id }",               // εγγραφή δεδομένου id (όπως η φόρμα), πχ: "/invoice/1"
    "{ id }/detail",        // εγγραφές detail δεδομένου id, πχ: "/invoice/1/invoiceItems"
    "{ id }/detail/{ id }", // ισότιμο με (1)
    "list",                 // λίστα εγγραφών (όπως ο πίνακας)
    "schema",               // ισότιμο με την αντίστοιχη επιλογή του GUI
    "stats",                // στατιστικά αρχείου
    "status"                // ισότιμο με την αντίστοιχη επιλογή του GUI
    ]
"meta"  : null
}

Με το list endpoint, διαβάζουμε τις γραμμές του αρχείου:

/api/crud/people/list/

{
"status": 200,
"result": 
    [
    {...},
    {...},
    ...,
    {...},
    {...},
    ]
"meta"  :
    {
    "rpp": 24,  // rows per page 
    "pgn": 1,   // page number
    "rwc": 905, // row count
    "pgc": 38   // page count
    }
}