Το ERP σας ως REST API με το Boomi

Αργά ή γρήγορα κάποιος ζητά άμεση πρόσβαση στο ERP: το e-shop θέλει αποθέματα σε πραγματικό χρόνο, ένας συνεργάτης θέλει την κατάσταση των παραγγελιών του, η εφαρμογή των πωλητών θέλει το ανοιχτό υπόλοιπο ενός πελάτη. Η γρήγορη απάντηση είναι να τους ανοίξετε το API του ίδιου του ERP. Σε αυτό το άρθρο εξηγούμε γιατί αυτό συνήθως γυρίζει μπούμερανγκ, περιγράφουμε το pattern που δουλεύει καλύτερα και το υλοποιούμε βήμα βήμα στο Boomi.

Το πρόβλημα με την απευθείας έκθεση του ERP

Τα APIs των ERP είναι σχεδιασμένα για το ERP, όχι για όσους τα καταναλώνουν:

Ακολουθούν τη δομή της βάσης του ERP. Για «το ανοιχτό υπόλοιπο ενός πελάτη» μπορεί να χρειάζονται τρεις κλήσεις και λίγη αριθμητική από την πλευρά του client.
Αποκαλύπτουν εσωτερικές λεπτομέρειες. Ονόματα πεδίων, κωδικοί και αριθμοί εταιρειών που έχουν νόημα μόνο μέσα στον οργανισμό σας καταλήγουν στον κώδικα των συνεργατών.
Αλλάζουν μαζί με το ERP. Μια αναβάθμιση ή μια μετάβαση σε άλλο ERP «σπάει» όλους τους clients μαζί.
Χρειάζονται ισχυρά διαπιστευτήρια. Οι χρήστες API ενός ERP έχουν συχνά πολύ περισσότερα δικαιώματα από όσα θα έπρεπε να έχει ένας μεμονωμένος client.

Το pattern: API facade

Ένα API facade είναι ένα μικρό, σταθερό API που σχεδιάζετε γύρω από αυτό που χρειάζονται οι χρήστες του. Πίσω του, ένα επίπεδο integration μεταφράζει κάθε κλήση σε ό,τι απαιτεί το ERP.

Clients ──► API facade (το συμβόλαιό σας) ──► λογική integration ──► ERP

Οι clients βλέπουν μόνο το facade. Μπορείτε να αλλάξετε, να αναβαθμίσετε ή να αντικαταστήσετε το ERP, και όσο το facade κρατά το συμβόλαιό του, κανείς έξω δεν το καταλαβαίνει.

Πρώτα το συμβόλαιο

Πριν ανοίξετε οποιοδήποτε εργαλείο, γράψτε το συμβόλαιο. Στο παράδειγμά μας εκθέτουμε ένα resource:

# Απόσπασμα περιγραφής OpenAPI
paths:
  /customers/{customerId}/balance:
    get:
      summary: Open balance of a customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Balance found
          content:
            application/json:
              example: { "customerId": "C-1042", "currency": "EUR", "openBalance": 1250.40, "overdue": 310.00 }
        '404':
          description: No such customer

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

Υλοποίηση στο Boomi

Στο Boomi, το facade αποτελείται από δύο κομμάτια: ένα integration process που κάνει τη δουλειά και ένα API Service component που ορίζει το REST συμβόλαιο και δρομολογεί κάθε endpoint σε ένα process.

Βήμα 1: Το process

Δημιουργήστε νέο process. Ρυθμίστε το Start shape με τον connector Web Services Server και το action Listen.
Στο operation, ορίστε input type None (ένα GET δεν έχει body) και output type Single JSON Object. Δημιουργήστε ένα JSON profile που αντιστοιχεί στην απάντηση 200 του συμβολαίου.
Διαβάστε το ID του πελάτη από το URL. Οι path parameters φτάνουν στο process ως dynamic document properties με το όνομα της παραμέτρου και πρόθεμα param_ (οι query parameters με query_). Εδώ είναι το param_customerId.
Καλέστε το ERP με τον connector του (ή με τον HTTP Client connector, αν το ERP έχει REST API) για να φέρετε τις ανοιχτές εγγραφές του πελάτη.
Με ένα Map shape μετατρέψτε την απάντηση του ERP στο JSON profile σας. Εδώ γίνεται η μετάφραση: μετονομασία πεδίων, υπολογισμός του overdue, αφαίρεση εσωτερικών κωδικών.
Τελειώστε με ένα Return Documents shape, ώστε το αποτέλεσμα να επιστρέψει στον καλούντα.

Βήμα 2: Σωστός χειρισμός του «δεν βρέθηκε»

Αν το ERP δεν επιστρέψει πελάτη, μην στείλετε ένα άδειο 200. Προσθέστε ένα Decision shape μετά την κλήση στο ERP. Στον κλάδο «δεν βρέθηκε», ορίστε status code 404 μέσω των document properties του Web Services Server και επιστρέψτε ένα σύντομο μήνυμα σφάλματος, όπως { "error": "customer_not_found" }. Έτσι οι clients χειρίζονται την περίπτωση χωρίς να μαντεύουν.

Βήμα 3: Το API Service component

Δημιουργήστε νέο API Service component και επιλέξτε τύπο REST.
Ορίστε base path, για παράδειγμα /erp/v1. Η έκδοση μέσα στο path κάνει εύκολο ένα μελλοντικό v2.
Προσθέστε ένα REST endpoint: method GET, resource path customers/{customerId}/balance, και επιλέξτε το process του βήματος 1.
Δείτε την τεκμηρίωση API που παράγεται. Το Boomi μπορεί να εξαγάγει περιγραφή OpenAPI, την οποία μπορείτε να συγκρίνετε με το συμβόλαιο που γράψατε.

Βήμα 4: Deploy και ασφάλεια του runtime

Κάντε deploy και το process και το API Service component στο ίδιο environment. Το API λειτουργεί μόνο αν το runtime (Atom, Molecule ή Atom Cloud) έχει και τα δύο.
Στις ρυθμίσεις Shared Web Server του runtime, ελέγξτε τον τύπο API και την ταυτοποίηση. Για μια πρώτη δοκιμή αρκεί Basic authentication με έναν αποκλειστικό χρήστη. Για παραγωγή, βάλτε ένα gateway μπροστά (δείτε παρακάτω).

Βήμα 5: Δοκιμή

Καλέστε το endpoint με οποιονδήποτε HTTP client. Αντικαταστήστε host, port και διαπιστευτήρια με αυτά του runtime σας:

curl -u api-user:token https://your-runtime-host:9090/ws/rest/erp/v1/customers/C-1042/balance

Πρέπει να πάρετε πίσω το JSON του συμβολαίου σας, όχι ένα παραστατικό του ERP. Δοκιμάστε μετά έναν άγνωστο πελάτη και ελέγξτε ότι παίρνετε 404.

Πριν βγείτε σε παραγωγή

Βάλτε ένα gateway μπροστά. Ο web server του runtime δεν προορίζεται να βλέπει απευθείας συνεργάτες. Ένα gateway προσθέτει API keys, rate limits και developer portal. Το καλύπτουμε στο Προστασία ενός API με keys και rate limits στο Boomi Cloud API Management.
Χρήστης ERP με ελάχιστα δικαιώματα. Το process χρειάζεται μόνο να διαβάζει υπόλοιπα, άρα και ο χρήστης ERP που χρησιμοποιεί πρέπει να μπορεί μόνο αυτό.
Καταγράψτε ένα correlation ID. Επιστρέψτε ένα ID σε header της απάντησης και καταγράψτε το στο process, ώστε ένα παράπονο συνεργάτη να εντοπίζεται σε συγκεκριμένη εκτέλεση.
Κρατήστε το συμβόλαιο σε version control. Το αρχείο OpenAPI είναι η πηγή αλήθειας, και οι αλλαγές του ελέγχονται όπως ο κώδικας.

Συνοψίζοντας

Το pattern του facade θέλει λίγο περισσότερο σχεδιασμό στην αρχή και τον αποπληρώνει την πρώτη φορά που αλλάζει το ERP. Στο Boomi, το process κρατά τη λογική μετάφρασης και το API Service component κρατά το συμβόλαιο, οπότε το καθένα αλλάζει χωρίς να επηρεάζει το άλλο. Για τη συνολική εικόνα, δείτε τον οδηγό μας Διαχείριση APIs: τι είναι και πότε τη χρειάζεστε.