API και Σχεδίαση Web Services: Θεωρία, Παραδείγματα και Πρακτικές Εφαρμογές μεταξύ Pylon ERP και WooCommerce.

Παναγιώτης Μωραϊτόπουλος

Jan 11, 2025 — 12 min read

Ορισμός του API

Το API προέρχεται από το Application Programming Interface ή Διεπαφή Προγραμματισμού Εφαρμογών. “Πιθανότατα πρωτοεμφανίστηκε το 1968 και ορίστηκε ως «μια συλλογή από ρουτίνες κώδικα που παρέχουν σε εξωτερικούς χρήστες δεδομένα και λειτουργίες δεδομένων»”(Santoro, et al., 2019)Πλέον, λόγω της ευρύτερης σημασίας και χρήσης του στην ανάπτυξη εφαρμογών, ως API ορίζονται «οι κλήσεις, οι υπό-ρουτίνες ή οι διακοπές λογισμικού που συνθέτουν μία τεκμηριωμένη διεπαφή, ώστε μία εφαρμογή να μπορεί να χρησιμοποιεί τις υπηρεσίες και τις λειτουργίες μίας άλλη εφαρμογής, λειτουργικού συστήματος, λειτουργικού συστήματος διαδικτύου, οδηγού ή άλλο πρόγραμμα λογισμικού χαμηλότερου επιπέδου.»(Shnier, 1996)

Νοητικό παράδειγμα ενός API

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

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

Σε αυτό το νοητικό παράδειγμα, μπορούμε να παραλληλίσουμε τους σερβιτόρους ως το API της κουζίνας. Οι πελάτες έρχονται σε επαφή με τον σερβιτόρο που του αναφέρουν τι θέλουν να καταναλώσουν. Οι σερβιτόροι επικοινωνούν με τη κουζίνα. Οι κουζίνα εκτελεί τις απαραίτητες διαδικασίες για τη παραγωγή του συγκεκριμένου πιάτου. Όταν το αποτέλεσμα είναι έτοιμο, οι σερβιτόροι προωθούν το πιάτο από τη κουζίνα στον πελάτη. Με αυτή τη διαδικασία, ο πελάτης δε χρειάζεται να μάθει και να δώσει ο ίδιος τις εντολές στη κουζίνα τι πρέπει και πως πρέπει να παραχθεί. Για τον πελάτη, η παραγγελία ενός πιάτου, αποτελεί μία διαδικασία black-box, η οποία του επιστρέφει το επιθυμητό αποτέλεσμα.

The API Restaurant Analogy. Εικόνα από το άρθρο What is an API (by Modifly) https://mobifly.tech/what-is-an-api

Στοιχεία του παγκόσμιου ιστού

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

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

Αυτό καλύπτεται με τη χρήση των Unique Resource Identifiers ή αλλιώς URIs. Κάθε URI αντιστοιχεί σε ένα μόνο πόρο του παγκόσμιου ιστού.

Τα URIs μπορούν να διαχωριστούν σε 2 κατηγορίες :

· URLs (Universal Resource Locator)

· URNs (Universal Resource Name)

Τα URIs έχουν συγκεκριμένη δομή.

· Scheme: Αναφέρεται στο πρωτόκολλο, όπως για παράδειγμα HTTP, HTTPS, FTP, MAILTO, IRC, FILE.

· Authority: Αναφέρεται στα εξής επιμέρους στοιχεία

o Userinfo: Προαιρετικό κομμάτι αυθεντικοποιήσης το οποίο μπορεί να έχει την εξής μορφή: user:password@

o Host: Διεύθυνση του Server

o Port: Προαιρετικό τμήμα και αναφέρεται σε συγκεκριμένη πόρτα του Server. Στη περίπτωση κάποιων πρωτοκόλλων υπάρχουν default ports όπως στο HTTP που είναι η 80 και στο HTTPS που είναι 443.

· Path: Αναφέρεται στη διαδρομή που υπάρχουν τα αρχεία, διαχωρισμένα με κάθετο (/)

· Query: Προαιρετικό τμήμα. Περιέχει μη ιεραρχημένα δεδομένα ξεκινώντας με ερωτηματικό (?) και ενώνονται με το συμπλεκτικό σύμβολο (&). Περιέχει παραμέτρους που θα χρησιμοποιηθούν στον Server.

· Fragment: Προαιρετικό τμήμα το οποίο προστίθεται μετά το σύμβολο κάγκελο (#).

Αναπαραστάσεις πόρων

Οι πόροι του παγκόσμιου ιστού μπορούν να χρησιμοποιήσουν διάφορες μορφές όπως XML, JSON, XHTML, CSV, text, form-data, x-www-form-urlencoded και άλλα.

Ένας πόρος είναι μια ψηφιακή αναπαράσταση μιας έννοιας, συχνά μιας οντότητας ή μιας συλλογής οντοτήτων που μπορεί να αλλάξει με την πάροδο του χρόνου. Αποτελείται από ένα μοναδικό όνομα ή αναγνωριστικό που μπορεί να παραπέμπει σε έγγραφα, εικόνες, συλλογές άλλων πόρων ή μια ψηφιακή αναπαράσταση οποιουδήποτε πράγματος στον πραγματικό κόσμο, όπως ένα πρόσωπο ή ένα πράγμα. Οι πόροι μπορεί ακόμη και να αναπαριστούν επιχειρηματικές διαδικασίες και ροές εργασίας. (Higginbotham, Principles of Web API Design: Delivering Value with APIs and Microservices, 2021)

Οι πόροι του παγκόσμιου ιστού βρίσκονται αποθηκευμένοι στους Servers κυρίως σε βάσεις και αρχεία. Η πρόσβαση σε αυτούς τους πόρους γίνεται μέσω αναπαραστάσεων και όχι απευθείας. Κατά τη κλήση ενός API, το API επιστρέφει τα δεδομένα σε κάποια μορφή αναπαράστασης, σαφώς ορισμένη. Ο client της επικοινωνίας πρέπει να γνωρίζει αυτή τη μορφή. Η συγκεκριμένη μορφή αναπαράστασης ονομάζεται contract.

Hyper Text Transfer Protocol

Το πρωτόκολλο HTTP, είναι ένα μοντέλο επικοινωνίας του παγκόσμιου ιστού και απευθύνεται σε επικοινωνίες εφαρμογών.

Το HTTP είναι ένα πρωτόκολλο ερωτήσεων-απαντήσεων μεταξύ ενός πελάτη (client) και ενός εξυπηρετητή (server) (client-server model). Ο client έχε σχεδιαστεί για να υποβάλει ερωτήματα στον server και ο server έχει σχεδιαστεί για να απαντάει στα ερωτήματα του client.

HTTP Verbs

GET

Η μέθοδος GET ζητά την αναπαράσταση του καθορισμένου πόρου. Οι αιτήσεις που χρησιμοποιούν τη μέθοδο GET θα πρέπει να ανακτούν μόνο δεδομένα.

HEAD

Η μέθοδος HEAD ζητά μια απάντηση πανομοιότυπη με μια αίτηση GET, αλλά χωρίς το σώμα της απάντησης.

POST

Η μέθοδος POST υποβάλλει μια οντότητα στον καθορισμένο πόρο, προκαλώντας συχνά μια αλλαγή στην κατάσταση ή παρενέργειες στο διακομιστή.

PUT

Η μέθοδος PUT αντικαθιστά όλες τις τρέχουσες αναπαραστάσεις του πόρου-στόχου με τα δεδομένα της αίτησης.

DELETE

Η μέθοδος DELETE διαγράφει τον καθορισμένο πόρο.

CONNECT

Η μέθοδος CONNECT εγκαθιστά ένα tunnel στον διακομιστή που προσδιορίζεται από τον πόρο-στόχο. Συνδέεται μέσω proxy server.

OPTIONS

Η μέθοδος OPTIONS περιγράφει τις επιλογές επικοινωνίας για τον πόρο-στόχο.

TRACE

Η μέθοδος TRACE εκτελεί δοκιμή επανάληψης μηνυμάτων κατά μήκος της διαδρομής προς τον πόρο-στόχο.

PATCH

Η μέθοδος PATCH εφαρμόζει μερικές τροποποιήσεις σε έναν πόρο.

(MSDN Web Docs, 2023)

Web APIs και Αρχές Σχεδίασης

Πόροι και Μοντέλα Δεδομένων

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

Τα μοντέλα δεδομένων ή αλλιώς τα σχήματα των βάσεων δεδομένων των εφαρμογών έχουν ως κύριο σκοπό σχεδιαστεί να προσφέρουν μία βέλτιστη απόδοση στην ανάγνωση και στην εγγραφή δεδομένων. Από την άλλη πλευρά τα Web APIs έχουν ως κύριο σκοπό να εδραιώσουν ένα χρήσιμο, ουσιαστικό και σταθερό δίαυλο επικοινωνίας μεταξύ της εφαρμογής και εξωτερικών εφαρμογών με τρόπο αφηρημένο, δηλαδή με ένα τρόπο υψηλότερου επιπέδου αυτού μίας βάσης δεδομένων και όχι απλά μία ανταλλαγή δεδομένων από το σημείο Α στο σημείο Β.

Προκλήσεις παρουσίασης μοντέλων δεδομένων ως APIs

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

Αρχικά, οι εφαρμογές και κυρίως τα ERPs, όπως φαίνεται από την ελληνική αγορά αναβαθμίζονται συχνά. Κάθε μήνα, οι vendors μπορεί να κυκλοφορούν έως και 5-10 εκδόσεις. Κάθε χρόνο μπορεί να προκύπτουν τουλάχιστον 4 major εκδόσεις. Σε κάθε έκδοση, οι βάσεις δεδομένων των ERPs αλλάζουν, προστίθενται και αφαιρούνται πίνακες, αναβαθμίζονται δεδομένα κ.ο.κ. Η άμεση ταύτιση των πόρων των API με τη βάση δεδομένων θα επέβαλε τακτικές αναβαθμίσεις όχι μόνο στη δική μας εφαρμογή που σχεδιάζουμε το API, αλλά κυρίως στους καταναλωτές των APIs. Επίσης, οι ομάδες ανάπτυξης που χρησιμοποιούν τα Web APIs αυτά θα πρέπει να ενημερώνονται συχνά για τις αλλαγές και να πραγματοποιούν αντίστοιχες αλλαγές στο κώδικά τους για να προσθέτουν ή αφαιρούν σύμφωνα με την εκάστοτε έκδοση.

Μία σχεσιακή βάση δεδομένων ενός ERP μπορεί να περιέχει από χιλιάδες μέχρι δεκάδες χιλιάδες πίνακες δεδομένων. Η απεικόνιση αυτών των πινάκων ως ξεχωριστά resources ενός Web API θα προκαλέσει υψηλό traffic τόσο στο δίκτυο που βρίσκεται η εφαρμογή, στον Application Server της εφαρμογής, στον SQL Server αλλά και στους αντίστοιχους Servers των τρίτων εφαρμογών που θα πρέπει να κάνουν επαναλαμβανόμενες κλήσεις για να βρουν τις συσχετίσεις μεταξύ των πινάκων. Η λειτουργία αυτή θα μοιάζει σαν η τρίτη εφαρμογή να πραγματοποιεί “sql queries” σε ένα-ένα πίνακα και να διατηρεί τα δεδομένα να τα συνθέτει προκειμένου να εντοπίσει τη πληροφορία που της χρειάζεται. Αυτό οδηγεί σε υψηλές ασυνέπειες των δεδομένων καθώς και υψηλό κίνδυνο. Επιπλέον, δε μπορούμε να είμαστε σίγουροι ότι η τρίτη εφαρμογή θα καταφέρει να βρει την απάντηση αφού η πληροφορία μπορεί να είναι είτε αποθηκευμένη σε κάποια μορφή που έχει νόημα μόνο στα όρια εντός του ERP, αλλά μπορεί και να υπάρχουν επιπλέον παράμετροι που μπορεί να μη γνωρίζει. Παράδειγμα, τέτοιων, σε μία σχεσιακή βάση αποτελούν οι αδύναμες οντότητες και οι πίνακες που δεν είναι οντότητες αλλά συνδέουν επιμέρους πίνακες με σχέση πολλά προς πολλά.

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

Πρέπει να γίνει αντιληπτό, ότι οι ομάδες που χρησιμοποιούν τα APIs άλλων εφαρμογών δεν γνωρίζουν τίποτα για την εφαρμογή αυτή, για τη δομή της, για το τρόπο οργάνωσής της καθώς και για τη σημασία πολλών χαρακτηριστικών. Αυτό που επιθυμούν είναι να λάβουν δεδομένα και λειτουργίες τα οποία η σημασία τους είναι κατανοητή και ανεξάρτητη από το τρόπο σχεδίασης του εκάστοτε ERP.

Πρακτικό Παράδειγμα

Για να γίνει αντιληπτό θα παρουσιαστεί ένα παράδειγμα από τις εφαρμογές Pylon και Woocommerce.

Χαρακτηριστικά Αποθέματος Pylon ERP

Για τις ανάγκες επιχειρήσεων που εμπορεύονται προϊόντα όπως ρούχα, στο Pylon υπάρχει το module «Χαρακτηριστικά Αποθέματος» (token 21). «Η αναλυτική διαχείριση των χαρακτηριστικών ειδών (συνήθως σε επίπεδο χρώματος και μεγέθους) σχεδιάστηκε για εκείνες τις επιχειρήσεις που χρειάζονται τα εργαλεία για να διαχωρίζουν τα είδη τους ανάλογα με χρώματα, μεγέθη ή κάποια ιδιαίτερα χαρακτηριστικά. Με τον τρόπο αυτό εξασφαλίζεται η βέλτιστη κωδικοποίηση και διαχείριση των πολλαπλών κωδικών κάθε είδους αποθήκης, ενώ παράλληλα εξασφαλίζει ότι οι όλες οι κινήσεις κάθε είδους θα είναι στοχευμένες και σύμφωνες με τα παραπάνω χαρακτηριστικά.»(Epsilon Net Support Department, 2020).

Ως Χαρακτηριστικά Αποθέματος εννοούνται οι ομάδες χαρακτηριστικών που μπορούν να επιλεγούν στο εκάστοτε είδος. Κάθε Χαρακτηριστικό Αποθέματος έχει (συνήθως και συγκεκριμένα στο δικό μας παράδειγμα) τύπο «Λίστα Τιμών». Αυτό σημαίνει ότι κάθε τέτοια ομάδα περιλαμβάνει ένα σύνολο Χαρακτηριστικών (γνωστή ως Λίστα Χαρακτηριστικών, επιλογές, δηλαδή, που είναι διαθέσιμες να επιλεγούν στα είδη. Κάθε είδος συνδέεται με έως τρία Χαρακτηριστικά Αποθέματος, ενώ ταυτόχρονα, σε κάθε είδος μπορούν να επιλεγούν ποιοι συνδυασμοί από τις Λίστες Χαρακτηριστικών είναι διαθέσιμες για το συγκεκριμένο είδος. Παρακάτω εμφανίζονται οι οθόνες και γίνεται εύκολα αντιληπτή η δομή του συγκεκριμένου module στο Pylon ERP.

Οθόνη Χαρακτηριστικών Αποθέματος. Στο αριστερό κομμάτι εμφανίζονται όλα τα Χαρακτηριστικά Αποθέματος και στο δεξί για το επιλεγμένο η Λίστα Χαρακτηριστικών. Στο συγκεκριμένο παράδειγμα εμφανίζονται τα χρώματα της εταιρίας Colours & Sons.

Οθόνη ειδών. Εμφανίζεται ένα είδος το οποίο παρακολουθείται από δύο χαρακτηριστικά αποθέματος. Το πρώτο είναι το Μέγεθος, το δεύτερο είναι το Χρώμα.

Απ' όλους τους εν δυνάμει συνδυασμούς των δύο Χαρακτηριστικών Αποθέματος, το συγκεκριμένο είδος παρακολουθεί μόνο όσους είναι επιλεγμένους. Το Πράσινο σημαίνει ότι ο συνδυασμός είναι ενεργός, το κόκκινο ότι είναι ενεργός σε κάποιο κύκλωμα (Πωλήσεις ή Αγορές, αναλόγως τί γράφει) και το γκρι ότι είναι απενεργοποιημένος ο συνδυασμός. Οι υπόλοιποι συνδυασμοί δεν είναι ενεργοί.

Από τη παραπάνω περίπτωση καταλαβαίνουμε ότι σε επίπεδο βάσεις οι σχετιζόμενοι πίνακες είναι:

1. Ο πίνακας των Χαρακτηριστικών Αποθέματος

2. Ο πίνακας των Λιστών Χαρακτηριστικών

3. Ο πίνακας των Ειδών

4. Ο πίνακας των διαθέσιμων συνδυασμών Λιστών Χαρακτηριστικών για το εκάστοτε είδος.

Χαρακτηριστικά Αποθέματος Woocommerce

Ας εξετάσουμε τώρα τη περίπτωση μίας τρίτης εφαρμογής, όπως ένα eShop σε Woocommerce.

Αρχικά, στο Woocommerce ένα είδος μπορεί να είναι απλό ή μεταβλητό. Είδη που είναι μεταβλητά παρακολουθούνται από Ιδιότητες (βλέπε Χαρακτηριστικά Αποθέματος).

Κάθε Ιδιότητα περιέχει Τιμές (βλέπε Λίστα Χαρακτηριστικών). Εφόσον οι Ιδιότητες έχουν χαρακτηριστεί ως «Παραλλαγές», τότε από τις τιμές των Ιδιοτήτων δημιουργούν οι παραλλαγές.

Διαθέσιμες Παραλλαγές (βλέπε συνδυασμοί)

Αρχικά το πρώτο που παρατηρούμε είναι ότι ένα είδος του Woo μπορεί να έχει περισσότερες από 3 ιδιότητες (Στο Pylon υπάρχουν έως 3 Χαρακτηριστικά Αποθέματος σε κάθε είδος.)

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

Κάθε παραλλαγή μπορεί να έχει διαφορετικά γνωρίσματα στο Woocommerce.

Έστω ότι θέλουμε να δημιουργήσουμε ένα API το οποίο να δίνει πρόσβαση στο Woocommerce σε αυτές τις πληροφορίες του Pylon ERP. Αν συνδέαμε τα resources του Pylon ERP API με το σχήμα της βάσης δεδομένων, το Woocommerce θα έπρεπε:

1. Να γνωρίζει πλήρως τη δομή του Pylon ERP, τους περιορισμούς και τη σημασία του κάθε δεδομένου στη βάση, όπως για παράδειγμα τα enumerations.

2. Να διαχειριστεί τουλάχιστον 4 διαφορετικά resources.

3. Να εκτελεί σειριακά αυτά τα 4 endpoints και να συνθέτει τα αποτελέσματα, ενώ τα διατηρεί στη μνήμη.

4. Σε περίπτωση οποιασδήποτε αλλαγής να αλλάζει το κώδικα του και να τον προσαρμόζει στις εκάστοτε αλλαγές.

Ο διαχειριστής της εφαρμογής Woocommerce θα έβλεπε στην ουσία 4 διαφορετικούς πίνακες σαν να τους έκανε εκτέλεση με SQL.

Σε αντίθετη περίπτωση, ο χρήστης θα μπορούσε να λάβει μία τέτοια απάντηση ενδεικτικά.

Ενδεικτική απεικόνιση resource ενός είδους που περιλαμβάνει και τους συνδυασμούς του σε Χρώμα - Μέγεθος.

Σημαντική Σημείωση

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

Συμπέρασμα

Συνοψίζοντας, τα resources ενός API δεν είναι απλώς η εκτέλεση SQL queries αλλά αντιπροσωπεύουν έναν αφαιρετικό μηχανισμό που επιτρέπει την ασφαλή και ελεγχόμενη πρόσβαση στα δεδομένα και τις λειτουργίες ενός συστήματος. Αυτό το abstraction layer καθιστά τα Web Services τη προγραμματιστική «πρόσοψη» (front-end), καθώς προσφέρουν μία καλά ορισμένη διεπαφή που αποκρύπτει την πολυπλοκότητα του υποκείμενου συστήματος, επιτρέποντας τη διαχείριση και την κατανάλωση των πόρων με τρόπο αποδοτικό και ανεξάρτητο από τις εσωτερικές υλοποιήσεις.