Αριστοτέλειο Πανεπιστήμιο Θεσσαλονίκης

Διπλωματική Εργασία

Ανάπτυξη RESTful APIs με τη χρήση της γλώσσας Gherkin και του OpenAPI Specification

Διπλωματικός Φοιτητής: Επιβλέποντες: Αναστάσιος Δημανίδης 7422 Επικ. Καθηγ. Ανδρέας Συμεωνίδης Μεταδιδακτορικός ερευνητής Κυριάκος Χατζηδημητρίου

Η Διπλωματική Εργασία αποτελεί μέρος των υποχρεώσεων για την απόκτηση του Διπλώματος Ηλεκτρολόγου Μηχανικού και Μηχανικού Ηλεκτρονικών Υπολογιστών στο

Intelligent Systems and Software Engineering Labgroup - ISSEL Τμήμα Ηλεκτρολόγων Μηχανικών και Μηχανικών Ηλεκτρονικών Υπολογιστών i Ευχαριστίες Κατ’ αρχήν, θα ήθελα να ευχαριστήσω τον Καθηγητή κ. Συμεωνίδη Ανδρέα, ως επιβλέποντα, για την εμπιστοσύνη που μου έδειξε με την ανάθεση της διπλωματικής εργασίας. Οι επισημάνσεις και οι παρατηρήσεις του τόσο επί της διπλωματικής συνολικά όσο και επί λογισμικού που αναπτύχθηκε ειδικά, ήταν για εμένα διδακτικές. Θα ήθελα επίσης να τον ευχαριστήσω και ως καθηγητή για τις ξεχωριστά ενδιαφέρουσες εργασίες που μας ανέθετε, για το ομαδικό κλίμα στο οποίο μας μύησε και για την διαθεσιμότητά του στο να ακούει τους προβληματισμούς μας. Θα ήθελα ακόμη να ευχαριστήσω τον Μεταδιδακτορικό Ερευνητή κ. Χατζηδημητρίου Κυριάκο, ως συνεπιβλέποντα, για την άμεση καθοδήγηση που παρείχε κατά την διάρκεια αυτής της εργασίας. Ήτανε πάντοτε σε ετοιμότητα για να συζητήσουμε τα όποια ζητήματα ανέκυπταν στην πορεία της διπλωματικής. Θα ήθελα επιπλέον να ευχαριστήσω το ISSEL Labgroup ως ομάδα. Οι τεχνολογίες που προωθούνται από το ISSEL είναι εξαιρετικά ενδιαφέρουσες και άμεσα συνδεδεμένες με την σημερινή αγορά εργασίας. Επιπρόσθετα, χάρη στο κοινό ενδιαφέρον της ομάδας για την επιστήμη των υπολογιστών και την τεχνολογία γενικότερα, καλλιεργείται ένα φιλικό προς την έρευνα κλίμα. Το χαρακτηριστικό αυτό αποτελεί σημαντικό κίνητρο για έναν νέο φοιτητή. Κλείνοντας θα ήθελα να ευχαριστήσω την μητέρα μου Σωτηρία, τον πατέρα μου Παναγιώτη και τα αδέρφια μου Χριστόφορο και Παύλο, που ήταν δίπλα μου κατά την διάρκεια αυτού του πτυχίου. Η υπομονή τους και η στήριξή τους ήταν απεριόριστη τόσο στα εύκολα όσο και στα δύσκολα. Η αμέριστη συμπαράστασή τους δύσκολα μπορεί να περιγραφεί με λέξεις. Ευχαριστώ και όλους τους συμφοιτητές και τις συμφοιτήτριες και όλους τους άλλους φίλους για τις εμπειρίες που έζησα μαζί τους στην διάρκεια αυτών των σπουδών. ii

Αφιερωμένο στην γιαγιά μου την Ελένη και στους γονείς μου… iii Περίληψη Η επιτυχής και ποιοτική εκπλήρωση των εξειδικευμένων απαιτήσεων του εκάστοτε πελάτη λογισμικού, απασχολεί συνεχώς τόσο την βιομηχανία λογισμικού όσο και την ακαδημαϊκή κοινότητα. Ως εκ τούτου, εμφανίστηκαν και εμφανίζονται μεθοδολογίες σχεδιασμού και ανάπτυξης λογισμικού που επιλύουν αυτό το πρόβλημα, όπως το Behavior-Driven Development (BDD) και η Agile φιλοσοφία γενικότερα. Ταυτόχρονα ο Παγκόσμιος Ιστός περνάει από ένα στάδιο ωρίμανσης. Η έννοια «Ο Παγκόσμιος Ιστός ως Πλατφόρμα Εφαρμογών» κυριαρχεί. Αναπόφευκτα πυροδοτούνται συζητήσεις που αφορούν την αποτελεσματική σχεδίαση και ανάπτυξη λογισμικού και στον Παγκόσμιο Ιστό. Οι τρέχουσες τάσεις της αγοράς δείχνουν ότι τεχνολογίες όπως το REST μπορούν να δώσουν απαντήσεις σε αυτές τις συζητήσεις.

Δεδομένου αυτού του πλαισίου, οι βασικοί στόχοι της διπλωματικής είναι δύο. Ο πρώτος στόχος είναι ο σχεδιασμός μίας μεθοδολογίας κατά την οποία οι λειτουργικές απαιτήσεις των RESTful Web APIs περιγράφονται σε φυσική γλώσσα, φιλική προς τον πελάτη. Ο δεύτερος στόχος είναι η ανάπτυξη ενός λογισμικού ικανού να μετατρέψει τις απαιτήσεις σε τεχνικές πληροφορίες. Προκειμένου να επιτευχθούν αυτοί οι στόχοι, υιοθετείται η γλώσσα συγγραφής απαιτήσεων Gherkin, η τυποποίηση REST υπηρεσιών OpenAPI Specification αλλά και μεθοδολογίες επεξεργασίας φυσικής γλώσσας.

Αρχικά, κατά την υλοποίηση του συνολικού συστήματος διερευνήθηκε ο τρόπος απεικόνισης REST απαιτήσεων σε Gherkin. Για τον λόγο αυτό πραγματοποιήθηκαν επικοινωνίες με στελέχη εταιριών Agile και BDD, εξετάσθηκαν blog και σεμινάρια εταιριών API και μελετήθηκε διεξοδικά η βιβλιογραφία. Με βάση αυτή την έρευνα, στην παρούσα εργασία σχεδιάστηκε η μεθοδολογία Re- source Driven Development (RDD). Κατά το RDD, αναθεωρείται η λογική συγγραφής των feature files της Gherkin. Πλέον οι απαιτήσεις λειτουργίας της Web εφαρμογής αφορούν αποκλειστικά την περιγραφή πόρων Παγκόσμιου Ιστού. Ακόμη, τα βήματα ‘When’ και ‘Then’ χρησιμοποιούνται πλέον για την μοντελοποίηση του πρωτοκόλλου HTTP. Επιπρόσθετα, τα σενάρια χρησιμοποιούνται για περιγραφή αλλαγής κατάστασης πόρου και εφαρμογής, με βάση την φιλοσοφία του REST. Τα ειδικότερα χαρακτηριστικά της μεθοδολογίας Gherkin αναλύονται διεξοδικά στην διπλωματική και παρουσιάζονται με συγκεκριμένα παραδείγματα. Στο επόμενο στάδιο της υλοποίησης του συνολικού συστήματος, αναπτύχθηκε σε python 3.5 το λογισμικό Gherkin2OAS, το οποίο μετατρέπει τις Gherkin απαιτήσεις σε OpenAPI Specifica- tion. Στην διπλωματική παρουσιάζεται αναλυτικά το μοντέλο λειτουργίας του λογισμικού, οι συναρτήσεις του και οι τεχνικές επεξεργασίας φυσικής γλώσσας που χρησιμοποιεί. Το λογισμικό είναι ικανό να εντοπίζει σε κείμενο φυσική γλώσσας HTTP ρήματα, ονόματα παραμέτρων, τύπους παραμέτρων (string, int, float, bool, array, file, date, password κ.α.) και ιδιότητες παραμέτρων (required, min/max, descriptions, formats), συνδέσεις πόρων με βάση το μοντέλο HATEOAS, ρόλους/χρήστες, HTTP status codes κ.α. Επίσης, έχει ξεχωριστή λειτουργία οργάνωσης αυτών των τεχνικών πληροφοριών σε OpenAPI Specification. Περαιτέρω προσπαθεί μέσω μηνυμάτων να καθοδηγήσει τον χρήστη στην συγγραφή των απαιτήσεων Gherkin, όπως ένας compiler.

Τέλος, στην παρούσα εργασία και ως μέρος του Gherkin2OAS, αναπτύχθηκε υποσύστημα απεικόνισης του RESTful API με γράφους. Οι γράφοι μπορούν να συνεισφέρουν στην κατά REST αξιολόγηση του συστήματος, στην επιβεβαίωση της επιτυχούς σύλληψης του επιχειρησιακού πρωτοκόλλου του πελάτη, στην διόρθωση λαθών και στην εξαγωγή τεχνικών πληροφοριών. Η χρήση των γράφων παρουσιάζεται με συγκεκριμένα παραδείγματα. Δημανίδης Τάσος [email protected] iv Abstract Employing the Gherkin language and the OpenAPI Specifi- cation for automated RESTful Web API Development The problem of the effective satisfaction of customer requirements in the typical software de- velopment lifecycle has been of major concern, not only to the software industry, but also to the academic world. Thus, new software development methodologies like Behavior-Driven Develop- ment and the Agile manifesto are introduced, dictating continuous and detailed communications between the software engineer and the customer. At the same time the World Wide Web is ma- turing. The concept “The Web as an Application Platform” is greatly adopted. Inevitably, Web developers and industry specialists are discussing methods of effectively designing and devel- oping Web applications. The current state of the industry shows that technologies like REST, might be the answer to those discussions.

This thesis sets two major goals: a) To design a methodology where RESTful Web API functional requirements are described in a customer friendly format and in natural language, b) To develop a software tool that will transform the described requirements to technical information. For these goals to be met we employ Gherkin -a user requirements language-, the OpenAPI Spec- ification -a specification for REST Web APIs- and finally Natural Language Processing (NLP) mechanisms.

At first, it was examined how would the REST specifications be mapped to Gherkin. For that reason, Agile and BDD company members were contacted, API company blogs and seminars were examined and the available bibliography was thoroughly studied. Based on this research, the methodology Resource Driven Development (RDD) was designed. Per RDD, the functional requirements of a Web application are organized in resources. Thus, the original way of writing Gherkin feature files was revised. The steps ‘When’ and ‘Then’ are now used to model the HTTP protocol. The scenarios are used to describe resource and application state changes, as implied by REST. The RDD methodology is described in detail with specific examples of Gherkin files.

The next step was to develop a software tool, which was named Gherkin2OAS and which is responsible of converting Gherkin requirements to the OpenAPI Specification. The software is written in python 3.5. It’s functionality, it’s functions and the NLP mechanisms it uses are thoroughly described. Gherkin2OAS can detect in natural language text HTTP verbs, parameter names, types (like string, int, float, bool, array, file, date, password and more) and properties (like required, min/max, descriptions and formats), resource linking through the HATEOAS concept, roles/users, HTTP status codes and more. It also has a separate functionality, where it organizes those technical properties to an OpenAPI Specification document. Furthermore, Gherkin2OAS has built in messages that try to guide the user in writing Gherkin requirements, the way a programming language compiler would help programming software.

Finally, a Gherkin2OAS subsystem was developed to visualize the created REST API with graphs. Those graphs can contribute in the REST evaluation of the system and in the success- ful realization of the client’s domain application protocol. It can also help with error fixing and technical information extraction. The graphs’ usage is presented with specific examples. Dimanidis Tasos [email protected] v Πίνακας Περιεχομένων

Ευχαριστίες i

Περίληψη iii

Abstract iv

Λίστα Εικόνων viii

Λίστα Πινάκων xiii

1 Εισαγωγή 1 1.1 Κίνητρο ...... 1 1.2 Περιγραφή προβλήματος ...... 1 1.3 Στόχοι διπλωματικής ...... 2 1.4 Διάρθρωση ...... 2

2 Υπόβαθρο 3 2.1 Representational State Transfer ...... 3 2.1.1 Αναδρομή στο παρελθόν ...... 3 2.1.2 Βασικές έννοιες του σύγχρονου Παγκόσμιου Ιστού ...... 4 2.1.2.1 Πόροι Παγκόσμιου Ιστού ή (Resources) ...... 5 2.1.2.2 Unique Resource Identifiers (URIs) ...... 5 2.1.2.3 Resource Representations ...... 7 2.1.2.4 Πρωτόκολλο HTTP ...... 8 2.1.3 Διδακτορική Διατριβή Roy Fielding ...... 10 2.1.4 Ο Παγκόσμιος Ιστός ως πλατφόρμα εφαρμογών ...... 14 2.1.4.1 Hypermedia as the engine of application state - HATEOAS 14 2.1.4.2 Ομοιόμορφη Διεπαφή - Uniform Interface στον Παγκόσμιο Ιστό ...... 17 2.1.5 RESTful Web APIs & OpenAPI Specification ...... 18 2.1.5.1 APIs ...... 18 2.1.5.2 OpenAPI Specification ...... 20 2.1.5.3 Τεχνικά χαρακτηριστικά του OpenAPI Specification .... 22 2.2 Behavior-Driven Development ...... 27 2.2.1 Σχεδιασμός και Ανάπτυξη Λογισμικού ...... 27 2.2.1.1 Test Driven Development ...... 29 2.2.1.2 Acceptance TDD και Behavior Driven Development .... 31 2.2.2 Gherkin ...... 37 2.3 Natural Language Processing ...... 41 2.3.1 Information Extraction ...... 41 2.3.1.1 Tokenization ...... 42 2.3.1.2 POS Tagging ...... 42 2.3.1.3 Text Chunking ...... 42 2.3.1.4 Named Entity Recognition ...... 43 2.3.1.5 Relation Extraction ...... 43 2.3.2 Άλλα εργαλεία NLP ...... 44 2.3.2.1 Κανονικές εκφράσεις (Regular Expressions) ...... 44 vi

2.3.2.2 Λίστες λέξεων ή φράσεων ...... 44 2.3.2.3 nltk ...... 44

3 Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 46 3.1 Σχετική βιβλιογραφία ...... 46 3.1.1 Εφαρμογή μηχανισμών NLP σε κείμενο λειτουργικών απαιτήσεων για εξαγωγή τεχνικών χαρακτηριστικών ...... 46 3.1.2 Web API Development με Gherkin ...... 47 3.2 Εξειδίκευση του προβλήματος: Ανάπτυξη Web APIs με την Gherkin και το OpenAPI Specification ...... 51 3.2.1 Agile RESTful API Development ...... 51 3.2.2 Λειτουργικές και μη, απαιτήσεις ...... 53 3.2.3 Απαιτήσεις συστήματος ...... 53

4 Μεθοδολογία & Υλοποίηση συστήματος 55 4.1 Μεθοδολογία ...... 55 4.1.1 Τεχνικό επίπεδο της Gherkin ...... 55 4.1.2 Απεικόνιση REST σε Gherkin ...... 56 4.1.3 Λογισμικό ...... 57 4.2 Υλοποίηση Συστήματος ...... 59 4.2.1 Απεικόνιση λειτουργικών απαιτήσεων REST συστήματος σε Gherkin: Resource Driven Development ...... 59 4.2.2 Gherkin2OAS ...... 67 4.2.3 Γράφοι καταστάσεων ...... 76 4.2.4 Gherkin2OAS Data Flows ...... 78 4.2.5 Gherkin2OAS Production Environment ...... 78

5 Πειράματα & Αποτελέσματα 87 5.1 Ο μηχανισμός διασφάλισης της αξιοπιστίας του συστήματος ...... 87 5.2 Ταχύτητα εκτέλεσης και POS Tagging ...... 89 5.3 Αναλυτικά Παραδείγματα, Πειράματα και αποτελέσματα ...... 90 5.3.1 Mytop10 API ...... 90 5.3.2 Generic e-shop ...... 103

6 Συμπεράσματα & Μελλοντικές επεκτάσεις 119 6.1 Συμπεράσματα ...... 119 6.1.1 Σχεδιασμού ...... 119 6.1.2 Υλοποίησης ...... 119 6.2 Μελλοντικές επεκτάσεις ...... 121 6.2.1 Παράμετροι ...... 121 6.2.2 Βήμα Given και φυσικότητα γλώσσας Gherkin ...... 121 6.2.3 Απεικόνιση μη λειτουργικών απαιτήσεων σε Gherkin ...... 121 6.2.4 HATEOAS Graphs ...... 122 6.2.5 Τυποποίηση του NLP Model & IDE ...... 122 6.2.6 OpenAPI Specification V3 ...... 122

A Cucumber 124 A.1 Cucumber Business Facing ...... 125 A.2 Cucumber Technology Facing ...... 127 A.3 Άλλα εργαλεία BDD/ΤDD/ATDD ...... 128

B Η τεχνολογία πριν το REST ή οι ανταγωνιστικές τεχνολογίες 131 vii

B.1 URI Tunneling με URI Templates ...... 131 B.2 RPC και REST-RPC Hybrid ...... 132 B.3 WS-* ...... 133

C Απαιτήσεις API κατά RDD & OpenAPI Specifications 136 C.1 Mytop10 ...... 136 C.2 Generic eshop ...... 160

D Gherkin Specifications Document 187

Βιβλιογραφία 189 viii Λίστα Εικόνων

2.1 Η εξέλιξη του Διαδικτύου ...... 4 2.2 Παραδείγματα URI ...... 6 2.3 Το μοντέλο πελάτη-εξυπηρετητή ...... 9 2.4 REST: Client-Server ...... 11 2.5 REST: Stateless ...... 12 2.6 REST: Cache ...... 12 2.7 REST: Uniform Interface ...... 13 2.8 REST: Layered System ...... 13 2.9 REST ...... 14 2.10 Το Richardson Maturity Model ...... 17 2.11 Οι εταιρείες του OpenAPI Initiative ...... 21 2.12 Διαδικτυακή κίνηση κλήσεων API της εταιρείας apigee ...... 21 2.13 Περιπτώσης χρήσης των ηλεκτρονικών υπηρεσιών της apigee ...... 22 2.14 Τα Data Types του OAI Specification ...... 23 2.15 OpenAPI Specification: Παράδειγμα Definitions ...... 25 2.16 OpenAPI Specification: Παράδειγμα πληροφοριών του API ...... 25 2.17 OpenAPI Specification: Παράδειγμα Paths Object ...... 26 2.18 Οι βασικές δραστηριότητες ανάπτυξης λογισμικού ...... 29 2.19 Διαδεδομένα μοντέλα ανάπτυξης λογισμικού ...... 30 2.20 Διάγραμμα εξέλιξης διαδικασίας TDD ...... 31 2.21 Ο κύκλος ζωής της μεθοδολογίας TDD ...... 32 2.22 Διαδικασία συγγραφής acceptance test ...... 32 2.23 Συμμετοχή διαφόρων ομάδων στην συγγραφή δοκιμών κατά BDD, ATDD, TDD ...... 37 2.24 Ένα Cucumber feature file ...... 38 2.25 Η λογική πύλη AND κατά Cucumber ...... 39 2.26 Το Abstract Syntax Tree του Gherkin Parser ...... 40 2.27 Αποτέλεσμα εφαρμογής POS Tagging και Text Chunking σε μία πρόταση . 42 2.28 Παράδειγμα εφαρμογής Named Entity Recognition ...... 43 2.29 Η διαδικασία του Information Extraction ...... 43 2.30 Αλφαβητική λίστα POS Tags του Penn Treebarnk project ...... 45

3.1 S-CASE: Επισήμανση απαιτήσεων ...... 48 3.2 S-CASE: Οντολογικό δέντρο εννοιολογικών κλάσεων ...... 49 3.3 Πρόταση σημασμένη με post tags και chunks ...... 50 3.4 Κείμενο σημασμένο με POS tags και structural dependencies ...... 50 3.5 Τα επίπεδα σχεδιασμού ενός API ...... 52

4.1 Gherkin2OAS: Preprocessor model ...... 70 4.2 Gherkin2OAS: nlp model ...... 71 4.3 Gherkin2OAS: Παράδειγμα μοντέλου γράφου ’resource_state’ ...... 72 4.4 Gherkin2OAS: Παράδειγμα μοντέλου γράφου ’state’ ...... 73 4.5 Αντιστοιχία γνωστών φράσεων με status codes ...... 74 4.6 Η αντιστοιχία ρημάτων αγγλικής γλώσσας με HTTP ρήματα/operations .. 74 4.7 Λίστες φράσεων μεγίστων και ελαχίστων ...... 75 ix

4.8 Gherkin2OAS: Εσωτερικό μοντέλο που χρησιμοποιείται στον formatter για επίλυση ιεραρχιών ...... 76 4.9 Γράφος μετάβασης καταστάσεων σε επίπεδο πόρων ...... 77 4.10 Ο γράφος μεταβάσης καταστάσεων σε επίπεδο εφαρμογής, σε user friendly μορφή ...... 79 4.11 Ο γράφος μεταβάσης καταστάσεων σε επίπεδο εφαρμογής, σε τεχνική μορφή 80 4.12 Gherkin2OAS: Data Flow ...... 81 4.13 Gherkin2OAS: Alternative Data Flow ...... 82 4.14 Gherkin2OAS: GUI ...... 82 4.15 Φάκελος με αρχεία resource ...... 82 4.16 Παράδειγμα αρχείου spec_config.ini ...... 83 4.17 Αρχεία εξόδου εκτέλεσης Gherkin2OAS ...... 83 4.18 Εποπτεία του API με τον swagger editor - Editor ...... 84 4.19 Εποπτεία του API με τον swagger editor - API UI ...... 85 4.20 Δοκιμή του API με τον swagger editor ...... 86

5.1 Mytop10: User resource - paths ...... 92 5.2 Mytop10: User resource - models ...... 93 5.3 Mytop10: User resource - security ...... 94 5.4 Mytop10: User resource - GET user ...... 94 5.5 Mytop10: User resource - PUT user ...... 95 5.6 Mytop10: User resource - PUT user examples ...... 95 5.7 Mytop10: User resource - DELETE user ...... 96 5.8 Mytop10: User resource - POST user ...... 97 5.9 Mytop10: List resource - paths ...... 97 5.10 Mytop10: List resource - GET ...... 98 5.11 Mytop10: List resource - PUT ...... 99 5.12 Mytop10: List resource - DELETE ...... 100 5.13 Mytop10: List resource - POST ...... 101 5.14 Mytop10: Admin resource - paths ...... 101 5.15 Mytop10: Admin resource - security ...... 102 5.16 Mytop10: Admin resource - GET ...... 103 5.17 Mytop10: Admin resource - POST ...... 104 5.18 Mytop10: Rate resource - paths ...... 104 5.19 Mytop10: Rate resource - POST ...... 105 5.20 Mytop10: Rate resource - required model ...... 105 5.21 Mytop10: Search resource - GET ...... 106 5.22 Mytop10: Follow list resource - POST ...... 107 5.23 Mytop10: Comment resource - POST ...... 108 5.24 Mytop10: Follow list resource - required model ...... 108 5.25 Mytop10: Comment resource - required model ...... 109 5.26 Mytop10: Gherkin2OAS execution ...... 110 5.27 Generic eshop: paths (1/2) ...... 111 5.28 Generic eshop: paths (2/2) ...... 112 5.29 Generic eshop: product model ...... 112 5.30 Generic eshop: basket post response ...... 113 5.31 Generic eshop: Γράφος με μεταβάσεις καταστάσεων σε επίπεδο πόρων ... 114 5.32 Generic eshop: Γράφος με μεταβάσεις καταστάσεων σε επίπεδο κατάστασης εφαρμογής ...... 115 5.33 Generic eshop: Νέος γράφος με μεταβάσεις καταστάσεων σε επίπεδο πόρων 116 x

5.34 Generic eshop: Νέος γράφος με μεταβάσεις καταστάσεων σε επίπεδο κατάστασης εφαρμογής ...... 117 5.35 Generic eshop: Προτροπή διόρθωσης γράφου ...... 118

A.1 Τα βασικά επίπεδα του Cucumber ...... 124 A.2 Cucumber testing stack: Η μεθοδολογία BDD κατά Cucumber ...... 125 A.3 Τα step definitions παίζουν τον ρόλο του μεταγλωττιστή ...... 128 A.4 Πώς το Cucumber εκτελεί ένα σενάριο ...... 130 xi Λίστα Παραδειγμάτων

2.1 Παράδειγμα JSON αναπαράστασης ...... 7 2.2 Παράδειγμα XML αναπαράστασης ...... 7 2.3 HTTP αίτημα πελάτη σε εξυπηρετητή ...... 9 2.4 HTTP απάντηση εξυπηρετητή σε πελάτη ...... 9 2.5 Απάντηση εξυπηρετητή με Hypermedia Control ...... 15 2.6 BDD User Story ...... 35 2.7 ATDD Acceptance Test ...... 35 4.1 Παράδειγμα περιγραφής API κατά Cucumber ...... 55 4.2 RDD: Παράδειγμα βήματος με http ρήμα ...... 60 4.3 RDD: Παράδειγμα βήματος με περισσότερα το ενός http ρήματα ...... 60 4.4 RDD: παράμετροι στο path ...... 61 4.5 RDD: παράμετροι σε query ...... 61 4.6 RDD: παράμετροι σε body ...... 62 4.7 RDD είδη πινάκων: Πίνακας με παραμέτρους στην πρώτη στήλη και παραδείγματα στην δεύτερη ...... 62 4.8 RDD είδη πινάκων: Πίνακας με παραμέτρους στην πρώτη γραμμή και παραδείγματα στην δεύτερη ...... 62 4.9 RDD είδη πινάκων: Πίνακας μόνο με ονόματα παραμέτρων ...... 63 4.10 RDD είδη πινάκων: Πίνακας με μία παράμετρο ...... 63 4.11 RDD είδη πινάκων: Πίνακας με μέγιστα και ελάχιστα ...... 63 4.12 RDD: περιγραφή μοντέλου ...... 63 4.13 RDD: status code ...... 64 4.14 RDD: HATEOAS links ...... 64 4.15 RDD: path hierarchies ...... 65 4.16 RDD: roles ...... 65 4.17 RDD: Ένα resource file ...... 65 4.18 RDD: Πλήρες resource file ...... 66 4.19 Εκκίνηση Gherkin2OAS - τερματικό ...... 79 5.1 Mytop10 user resource ...... 90 5.2 Mytop10 list resource ...... 93 5.3 Mytop10 admin resource ...... 96 5.4 Mytop10 rate resource ...... 98 5.5 Mytop10 search resource ...... 99 5.6 Mytop10 search resource ...... 101 5.7 Generic eshop: all HATEOAS links ...... 103 5.8 Generic eshop: GET order - διπλή περιγραφή ...... 109 5.9 Generic eshop: Δημιουργία resource pending deliveries ...... 109 A.1 Πλεονάζοντα σενάρια Cucumber ...... 126 A.2 Cucumber Scenario Outline ...... 126 A.3 cucumber step definition ...... 127 B.1 Remote Procedure Call με XML ...... 132 B.2 POX μέσω HTTP ...... 133 B.3 SOAP Envelope ...... 133 B.4 Παράδειγμα WSDL αρχείου ...... 134 C.1 Mytop10 με RDD: user.resource ...... 136 C.2 Mytop10 με RDD: admin.resource ...... 137 xii

C.3 Mytop10 με RDD: comment.resource ...... 138 C.4 Mytop10 με RDD: follow list.resource ...... 138 C.5 Mytop10 με RDD: list.resource ...... 138 C.6 Mytop10 με RDD: rate.resource ...... 139 C.7 Mytop10 με RDD: search.resource ...... 140 C.8 Mytop 10 με RDD: OpenAPI Specification ...... 142 C.9 Eshop με RDD: product.resource ...... 161 C.10 Eshop με RDD: search.resource ...... 162 C.11 Eshop με RDD: basket.resource ...... 162 C.12 Eshop με RDD: order.resource ...... 163 C.13 Eshop με RDD: payment.resource ...... 164 C.14 Eshop με RDD: pending deliveries.resource ...... 164 C.15 Eshop με RDD: OpenAPI Specification ...... 166 xiii Λίστα Πινάκων

2.1 Safety & Idempotency των POST, GET, PUT, DELETE ...... 18 2.2 Acceptance test με στόχο την επικύρωση ενός επιχειρησιακού κανόνα ... 33 2.3 Acceptance test με στόχο την επικύρωση μέρους διεπαφής χρήστη ..... 34 1 Κεφάλαιο 1

Εισαγωγή

1.1 Κίνητρο

Το κίνητρο της διπλωματικής προέρχεται από το ερώτημα ”Ποια είναι η χρησιμότητα του λογισμικού στον άνθρωπο;”. Η απάντηση σε αυτό το ερώτημα είναι ότι το λογισμικό συνεισφέρει στους γρήγορους υπολογισμούς και στην γρήγορη επικοινωνία των ανθρώπων1. Οι ιδιότητες των γρήγορων υπολογισμών και της γρήγορης επικοινωνίας αξιοποιούνται στη συνέχεια σε αμέτρητες εμπορικές και ερευνητικές εφαρμογές. Όσο αυτές οι ιδιότητες του λογισμικού εκτιμούνται, τόσο το λογισμικό θα παραμένει επίκαιρο. Με δεδομένα τα πλεονεκτήματα του λογισμικού, το ερώτημα που πλέον απασχολεί είναι ”Πώς θα μεγιστοποιήσουμε την χρησιμότητα του λογισμικού στον άνθρωπο;”. Πιο συγκεκριμένα, δεδομένου ενός τεχνολογικά καταρτισμένου και αιτούμενου λογισμικού ανθρώπου (άρα αποδεχόμενου τα πλεονεκτήματα του λογισμικού), πώς θα σχεδιάσουμε το ζητούμενο λογισμικό, ώστε να υπηρετεί κατά το δυνατόν καλύτερα τις απαιτήσεις του; Αλλά και ταυτόχρονα, πώς μπορεί η ίδια η διαδικασία ανάπτυξης λογισμικού να βελτιωθεί, διατηρώντας ταυτόχρονα την ποιότητά του; Τα πλεονεκτήματα του λογισμικού, τα δύο τελευταία ερωτήματα και το ερευνητικό ενδιαφέρον της επίλυσής τους αποτελούν το κίνητρο της διπλωματικής.

1.2 Περιγραφή προβλήματος

Η ανάπτυξη των RESTful Web APIs εντάσσεται στην γενικότερη κατηγορία ανάπτυξης λογισμικού. Άρα κατ’ αρχήν για τα APIs ισχύει ό,τι ισχύει και για το λογισμικό. Ύστερα από αναζήτηση σε ιστοσελίδες, blog, και web seminars γνωστών εταιρειών του χώρου (Apigee, Apiary, SmartBear, 3Scale, apinf), φαίνεται ότι οι Agile μεθοδολογίες, άρα και το BDD, κυριαρχούν. Τα Web APIs πριν γίνουν διαθέσιμα, υπόκεινται σε μία σειρά από ελέγχους. Έτσι, μεθοδολογίες οι οποίες βασίζονται στην σχεδίαση λογισμικού ξεκινώντας από το τεστ, βρίσκουν εδώ εφαρμογή. Το πρόβλημα λοιπόν της διπλωματικής είναι, πώς θα σχεδιάσουμε ένα σύστημα που θα συμβάλλει στην ανάπτυξη RESTful Web APIs. Το σύστημα πρέπει να προβλέπει πώς οι απαιτήσεις των χρηστών θα γράφονται με την λογική του BDD. Επίσης ότι το τελικό του προϊόν δεν θα είναι το ίδιο το API, αλλά μία τυποποίηση για RESTful Web APIs, η Ope- nAPI Specification. Επισημαίνουμε τέλος ότι με βάση την έρευνα που έγινε2, τέτοιο σύστημα δεν υπάρχει. Άρα η σχεδίαση του συστήματος δεν μπορεί να βασιστεί σε υπαρκτά παραδείγματα,

1Η επιλογή της λέξης συνεισφορά δεν είναι τυχαία, διότι σε αυτά συνεισφέρει και το υλικό αλλά κυρίως η ανθρώπινη σκέψη. 2Η έρευνα συμπεριελάμβανε και επικοινωνία με στέλεχος της Cucumber αλλά και agile mentor Κεφάλαιο 1. Εισαγωγή 2

αλλά σε κάποιες βασικές αρχές. Ο εντοπισμός των αρχών είναι και αυτός μέρος του προβλήματος.

1.3 Στόχοι διπλωματικής

Οι στόχοι της διπλωματικής είναι δύο: 1. Ο σχεδιασμός μίας απεικόνισης του OpenAPI Specification σε γλώσσα Gherkin, ικανή να διαβαστεί από τον πελάτη. Η απεικόνιση θα πρέπει να έχει μορφή λειτουργικών απαιτήσεων. 2. Η ανάπτυξη λογισμικού ικανού να μετατρέπει τις καταγραφόμενες σε Gherkin λειτουργικές απαιτήσεις, σε OpenAPI Specification με την χρήση μηχανισμών επεξεργασίας φυσικής γλώσσας

1.4 Διάρθρωση

Η διπλωματική ξεκινάει με το θεωρητικό και πρακτικό υπόβαθρο το οποίο περιγράφεται στο Κεφάλαιο 2. Στην Ενότητα 2.1 περιγράφονται οι έννοιες του Παγκόσμιου Ιστού και των REST συστημάτων. Στην Ενότητα 2.2 περιγράφονται οι έννοιες της Τεχνολογίας Λογισμικού, των μεθοδολογιών Test Driven Development, Acceptance Test Driven Devel- opment και Behavioral Driven Development καθώς και η γλώσσα Gherkin. Στην Ενότητα 2.3 περιγράφονται έννοιες του Natural Language Processing, οι οποίες χρησιμοποιούνται στην μετατροπή από Gherkin σε OpenAPI Specification. Στην συνέχεια, στο Κεφάλαιο 3 γίνεται η επισκόπηση της σχετικής βιβλιογραφίας και εξειδικεύεται το πρόβλημα. Στο Κεφάλαιο 4 παρουσιάζεται η μεθοδολογία ανάπτυξης και η υλοποίηση του συστήματος. Στο Κεφάλαιο 5 παρουσιάζονται τα πειράματα και η αξιολόγησή τους. Στο Κεφάλαιο 6 καταλήγουμε στα συμπεράσματα και επισημαίνουμε μελλοντικές πτυχές του συστήματος. Τέλος στο Παράρτημα παρουσιάζεται σύντομα το εργαλείο Cucumber, οι ανταγωνιστικές τεχνολογίες του REST, παραδείγματα αρχείων γραμμένων με την γλώσσα του συστήματος και η τυποποίηση της γλώσσας Gherkin όπως ορίστηκε από το σύστημα. Στα Κεφάλαιο 2 η επισκόπηση των εννοιών είναι εκτενής, όχι τυχαία. Επειδή ακριβώς δεν υπάρχουν τα επιθυμητά παραδείγματα περιγραφής απαιτήσεων REST APIs σε Gherkin, έπρεπε οι έννοιες να κατανοηθούν κατά το δυνατόν περισσότερο. Δηλαδή οι έννοιες αυτές δεν επεξηγούνται μόνο για την κατανόηση του κειμένου, αλλά και επειδή οι ιδιότητές τους συνέβαλαν στην απεικόνιση του OpenAPI Specification σε Gherkin. 3 Κεφάλαιο 2

Υπόβαθρο

Στο κεφάλαιο αυτό γίνεται μία εκτενής επισκόπηση των απαραίτητων θεωρητικών και πρακτικών εννοιών τις οποίες χρειάζεται να γνωρίζει ο αναγνώστης, ώστε να καταλάβει την λειτουργία του συστήματος που σχεδιάστηκε. Επισημαίνεται ότι οι έννοιες αυτές δεν επεξηγούνται μόνο διότι είναι απαραίτητη η κατανόησή τους, αλλά και γιατί βάσει αυτών σχεδιάστηκε η μεθοδολογία απεικόνισης λειτουργικών απαιτήσεων RESTful υπηρεσιών σε γλώσσα Gherkin. Ειδικότερα, τα βασικά δομικά στοιχεία σχεδίασης Web εφαρμογών που περιγράφονται στις Ενότητες 2.1.2, 2.1.4.1 και 2.1.4.2 αλλά και η γενικότερη φιλοσοφία ανάπτυξης λογισμικού που περιγράφεται στην Ενότητα 2.2, αποτελούν την σχεδιαστική βάση του συστήματος που αναπτύχθηκε.

2.1 Representational State Transfer

2.1.1 Αναδρομή στο παρελθόν

Προκειμένου να μιλήσουμε για REST, πρέπει πρώτα να μιλήσουμε για τον Παγκόσμιο Ιστό και να αναφερθούμε στο Διαδίκτυο και στους ηλεκτρονικούς υπολογιστές. Από τους επεξεργαστές λοιπόν ο άνθρωπος αρχίζει να κατασκευάζει ηλεκτρονικούς υπολογιστές. Το επόμενο στάδιο είναι η επικοινωνία των ηλεκτρονικών υπολογιστών, δηλαδή τα δίκτυα ηλεκτρονικών υπολογιστών. Τα πρώτα δίκτυα είχαν στρατιωτικές (ARPANET) και ερευνητικές (NPL, Merit, CYCLADES) εφαρμογές [9]. Το ARPANET συγκεκριμένα ήταν αποτέλεσμα της έρευνας του Defense Advanced Research Projects Agency (DARPA) των Ηνωμένων Πολιτειών της Αμερικής (τέλη δεκαετίας 1960). Η πρόσβαση στο ARPANET, εντός των ΗΠΑ, διευρύνεται με την ίδρυση του CSNET (Computer Science Network). Το τελευταίο έχει, όπως φαίνεται και από το όνομά του, ερευνητικό σκοπό. Ήδη (1974, RFC-675 [26]) έχει εμφανιστεί η έννοια Internet ή Διαδίκτυο. Δηλαδή πολλά μικρά δίκτυα συνδεδεμένα εσωτερικά μεταξύ τους (inter-connected/inter-net). Η τυποποίηση RFC-675 ορίζει το πρωτόκολλο Transmission Control Protocol ή απλά TCP [30]. Το TCP είναι ένα πρωτόκολλο με στόχο, να διασφαλίζει την αξιόπιστη μετάδοση bits σε ένα δίκτυο υπολογιστών. Στην συνέχεια το DARPA εξελίσσει το TCP σε TCP/IP (συγκεκριμένα το TCP/IP v4). Πλέον συμπεριλαμβάνεται και το Internet Protocol ή απλά IP [12]. Το IP είναι πρωτόκολλο επικοινωνίας. Μαζί με το TCP αποτελούν το Internet Protocol Suite [13] ή απλά το TCP/IP. Η εφεύρεση του TCP/IP αποτελεί σημείο σταθμό στην εξέλιξη του Διαδικτύου.

Το 1982 το TCP/IP χρησιμοποιείται για όλες τις στρατιωτικές επικοινωνίες του ARPANET. Η εφεύρεση του TCP/IP οδηγεί επίσης στην εξέλιξη του CSNET στο NSFNet (National Science Foundation Network). Δίκτυο δηλαδή που προσπαθεί να συνδέσει όλα τα επιστημονικά δίκτυα των ΗΠΑ. Η πρώτη συστηματική διατλαντική επικοινωνία μεταξύ του NSFNet και των ερευνητικών/πανεπιστημιακών δικτύων της Κεφάλαιο 2. Υπόβαθρο 4

Εικόνα 2.1: Η εξέλιξη του Διαδικτύου2

Ευρώπης καθιερώνεται το 1988 (δορυφορική επικοινωνία Princeton-Stockholm). Πλέον το Διαδίκτυο παίρνει παγκόσμιες διαστάσεις. Το 1990 το ARPANET με την στρατιωτική του χροιά, αποτελεί παρελθόν. Ήδη το δίκτυο των ΗΠΑ έχει πάρει εμπορική μορφή. Την ίδια χρονιά (Μάρτιος 1990) εγκαθίσταται ο πρώτος μεγάλου εύρους ζώνης (1.5 ΜΒit/s) σύνδεσμος μεταξύ του NSFNet (Πανεπιστήμιο Cornell) και του ερευνητικού κέντρου CERN. Έξι μήνες αργότερα ο Tim Berners-Lee ξεκινάει την συγγραφή του Παγκόσμιου Ιστού (World Wide Web). Οι Leonard Richardson και Sam Ruby στο βιβλίο τους ”REST- ful Web Services”, αποτυπώνουν αυτή την πορεία με τον δικό τους τόνο:

”The Internet and the Web did not have to exist. They come to us courtesy of mis- allocated defense money, skunkworks engineering projects, worse-is-better engineering practices, big science, naive liberal idealism, cranky libertarian politics, technofetishism, and the sweat and capital of programmers and investors who thought they’d found an easy way to strike it rich.” [20]

Η εφεύρεση του Παγκόσμιου Ιστού από τον Tim Berners-Lee αποτελεί σημείο αναφοράς για την παγκοσμιοποίηση του Διαδικτύου. Κομμάτι αυτής της παγκοσμιοποίησης είναι και οι υπηρεσίες Παγκοσμίου Ιστού τύπου REST. Αλλά προκειμένου να κατανοήσει κάποιος τις εξελιγμένες τεχνολογίες του Παγκόσμιου Ιστού, πρέπει πρώτα να κατανοήσει τις βασικές έννοιες πάνω στις οποίες δημιουργήθηκε.

2.1.2 Βασικές έννοιες του σύγχρονου Παγκόσμιου Ιστού

Ο Παγκόσμιος Ιστός σήμερα, είναι ένας ηλεκτρονικός χώρος πληροφοριών παγκόσμιας εμβέλειας. Η μεγάλη εμπορική αποδοχή του Διαδικτύου στα τέλη του 20 αιώνα συνετέλεσε στην καθιέρωση ιδιαίτερα απλών εννοιών, οι οποίες σήμερα θεμελιώνουν τον Παγκόσμιο

2http://www.internetsociety.org/sites/default/files/images/timeline.gif Κεφάλαιο 2. Υπόβαθρο 5

Ιστό3. Οι βασικές αυτές έννοιες αφορούν τόσο τις διαθέσιμες πληροφορίες, όσο και την επικοινωνία των εφαρμογών που εκτελούνται στον Παγκόσμιο Ιστό. Έτσι η σύντομη επεξήγηση τους, κρίνεται σκόπιμη.

2.1.2.1 Πόροι Παγκόσμιου Ιστού ή (Resources)

Ένας πόρος του Παγκόσμιου Ιστού είναι οτιδήποτε διαθέτουμε προς πρόσβαση στον Παγκόσμιο Ιστό. Όπως για παράδειγμα ένα έγγραφο, κάθε είδους πολυμέσα, μία επιχειρησιακή διαδικασία, μία συσκευή, ένα ολόκληρο σύστημα. Οι πόροι του Παγκόσμιου Ιστού αποτελούν μερικές αναπαραστάσεις πραγματικών πόρων. Με την έννοια ότι έχουμε διατηρήσει τόσο την χρήσιμη όσο και την ικανή να προβληθεί στον Παγκόσμιο Ιστό πληροφορία.

Οι πόροι είναι η ουσία και ο λόγος ύπαρξης του Παγκόσμιου Ιστού. Ο ίδιος ο στόχος του Tim Berners-Lee ήταν να δημιουργήσει ένα σύστημα, ώστε η πρόσβαση σε πληροφορίες να καθίσταται απλή. Οποιαδήποτε συναναστροφή μας με τον Παγκόσμιο Ιστό, αναπόφευκτα έχει να κάνει με πόρους. Μέσω των πόρων φτάνουμε σε έναν τελικό σκοπό, όπως για παράδειγμα η παραγγελία ενός προϊόντος ή η προβολή ενός βίντεο.

2.1.2.2 Unique Resource Identifiers (URIs)

Τους πόρους στον Παγκόσμιο Ιστό τους συναντάμε σε εξυπηρετητές (servers). Ας εξετάσουμε τώρα το εξής παράδειγμα: Η ιστοσελίδα http://www.youtube.com, ή πολύ απλά το γνωστό σε όλους youtube, είναι μία υπηρεσία προβολής βίντεο. Ανάμεσα στο πολλά είδη πόρων που διαθέτει στους χρήστες της, ο πιο γνωστός είναι τα βίντεο. Το ερώτημα που τίθεται είναι, πώς θα ζητήσω ένα συγκεκριμένο video από την υπηρεσία youtube; Ή για να το γενικεύσουμε: Πώς μπορώ να απευθυνθώ σε έναν συγκεκριμένο πόρο ενός εξυπηρετητή; Και γενικότερα τι είναι αυτό που διακρίνει τον ένα πόρο από έναν άλλο, τόσο εντός ενός εξυπηρετητή όσο και γενικότερα εντός του Παγκόσμιου Ιστού?

Την απάντηση σε αυτό το ερώτημα δίνει η αρχιτεκτονική του Παγκόσμιου Ιστού με τα Unique Resource Identifiers. Τα Unique Resource Identifiers, ή για συντομία URIs, προσδιορίζουν ένα resource στον Παγκόσμιο Ιστό. Μέσω των URIs καθίστανται τα resource προσβάσιμα. Ένα Unique Resource Identifier αντιστοιχεί σε έναν -και μόνο έναν- πόρο του Παγκόσμιου Ιστού. Αντίθετα σε ένα resource μπορούν να αντιστοιχούν παραπάνω από ένα URIs. Έτσι η σχέση URIs - Resources είναι πολλά προς ένα.

Ένα παράδειγμα URI που προσδιορίζει ένα βίντεο στην υπηρεσία youtube είναι το ακόλουθο: https://www.youtube.com/watch?v=zecueq-mo4M. Η διεύθυνση του εξυπηρετητή στον οποίο βρίσκονται τα resources του youtube είναι το www.youtube.com. Αυτό το πρόθεμα διαχωρίζει τα resources του youtube από τα resources όλων των άλλων εξυπηρετητών του διαδικτύου. Εντός του εξυπηρετητή τώρα, το πρόθεμα /watch?v=zecueq-mo4M ξεχωρίζει το συγκεκριμένο βίντεο από όλα τα άλλα βίντεο του youtube αλλά και από όλες τις άλλες υπηρεσίες του (όπως για παράδειγμα το URI https://www.youtube.com/channel/UCEgdi0XIXXZ-qJOFPf4JSKw που περιέχει τα βίντεο με τα sport). Το εκάστοτε εσωτερικό πρόθεμα προσδιορισμού resource ονομάζεται

3Επισημαίνουμε εδώ ότι ο Παγκόσμιος Ιστός είναι υπηρεσία του Διαδικτύου και όχι το Διαδίκτυο. Είναι μάλιστα η πιο χρησιμοποιημένη υπηρεσία του Διαδικτύου. Γι’ αυτό πολλές φορές στην καθημερινότητά μας συγχέουμε τις δύο έννοιες. Άλλες υπηρεσίες του διαδικτύου είναι για παράδειγμα το ηλεκτρονικό ταχυδρομείο, η διαδικτυακή τηλεφωνία, τα δίκτυα peer-to-peer και το ευρέως γνωστό πλέον cloud [3][4] Κεφάλαιο 2. Υπόβαθρο 6 path. Γενικώς ένα URI αναλύεται ως εξής4: scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]

Το URI αποτελείται: • Από το scheme το οποίο είναι μία ακολουθία χαρακτήρων που περιγράφει το πρωτόκολλο επικοινωνίας. Δημοφιλή πρωτόκολλα επικοινωνίας είναι τα http (Παγκόσμιος Ιστός), ftp, mailto, file, data και irc • Από δύο πλάγιες καθέτους (//). Η ύπαρξη ή όχι πλάγιων καθέτων εξαρτάται από την τυποποίηση του scheme. • Από το authority part το οποίο αποτελείται: – Από ένα προαιρετικό κομμάτι αυθεντικοποίησης (authentication) με όνομα χρήση και κωδικό. Το όνομα χρήστη χωρίζεται από τον κωδικό με άνω κάτω τελεία (:). Στο τέλος του κομματιού αυθεντικοποίησης πρέπει να υπάρχει το σύμβολο ”at” (@). – Από την διεύθυνση του εξυπηρετητή (host) – Από έναν προαιρετικό αριθμό πόρτας (port number), ο οποίος διαχωρίζεται από τον host με άνω κάτω τελεία (:). • Από το path το οποίο περιέχει δεδομένα. Τα δεδομένα συνήθως αναπαρίστανται σε ιεραρχική μορφή σε κομμάτια που διαχωρίζονται από μονές πλάγιες καθέτους (/). • Από ένα προαιρετικό query μετά το path. Το query περιέχει επίσης δεδομένα, μη ιεραρχικά δομημένα, συνήθως χωρισμένα με το σύμβολο ”και” (&) ή το ελληνικό ερωτηματικό (;) • Από ένα προαιρετικό fragment το οποίο εμφανίζεται μετά από το σύμβολο ”κάγκελο” (#). Το fragment αναφέρεται σε δευτερεύον resource, όπως για παράδειγμα ένα υπό κεφάλαιο ενός κειμένου. Παράδειγμα URI φαίνεται στην Εικόνα 2.2.

Εικόνα 2.2: Παραδείγματα URI4

Συνεπώς από το URI μπορούμε να διαπιστώσουμε το πρωτόκολλο επικοινωνίας, να διακρίνουμε έναν εξυπηρετητή από έναν άλλον, αλλά και να διακρίνουμε

4https://en.wikipedia.org/wiki/Uniform_Resource_Identifier Κεφάλαιο 2. Υπόβαθρο 7

ένα συγκεκριμένο resource του εξυπηρετητή από τα υπόλοιπα resource του ίδιου εξυπηρετητή. Δηλαδή τα URIs περιέχουν ποιοτική και χρήσιμη πληροφορία.

2.1.2.3 Resource Representations

Οι πόροι του Παγκόσμιου Ιστού εμφανίζονται με διάφορες μορφές. Έτσι για παράδειγμα συναντάμε μορφές όπως XHTML, Atom, XML, JSON, απλό κείμενο, comma-separated values (CSV), MP3, JPEG και πολλά άλλα. Ένας πόρος μπορεί να παρουσιάζεται με παραπάνω από μία μορφές. Οι μορφές παρουσίασης των πόρων ονομάζονται αναπαραστάσεις. Τέτοιες αναπαραστάσεις φαίνονται στα παραδείγματα 2.1 και 2.2.

Παράδειγμα 2.1: Παράδειγμα JSON αναπαράστασης {"employees":[ {"firstName":"John", "lastName":"Doe"}, {"firstName":"Anna", "lastName":"Smith"}, {"firstName":"Peter", "lastName":"Jones"} ]}

Παράδειγμα 2.2: Παράδειγμα XML αναπαράστασης John Doe Anna Smith Peter Jones

Στην πραγματικότητα, ποτέ δεν απευθυνόμαστε σε ένα πόρο απευθείας. Οι πόροι βρίσκονται αποθηκευμένοι σε βάσεις δεδομένων και μνήμες ηλεκτρονικών υπολογιστών. Όταν μία εφαρμογή επεξεργάζεται έναν πόρο, δεν επεξεργάζεται απευθείας την βάση δεδομένων στην οποία αυτός είναι αποθηκευμένος. Εδώ πρέπει να θυμηθούμε ότι ο Παγκόσμιος Ιστός είναι πρωτόκολλο εφαρμογών. Έτσι εξ’ ορισμού δεν υποστηρίζεται την πρόσβαση σε τόσο χαμηλού επιπέδου πληροφορίες. Κυρίως όμως δεν είναι ο σκοπός του Παγκόσμιου Ιστού η επικοινωνία τέτοιων δεδομένων. Αυτό το οποίο είναι διαθέσιμο από τους διάφορους εξυπηρετητές του Παγκόσμιου Ιστού είναι οι αναπαραστάσεις των πόρων. Εδώ κάποιος μπορεί να θέσει το ερώτημα: Το βίντεο το οποίο είναι αποθηκευμένο στην βάση δεδομένων του youtube δεν είναι ίδιο με την αναπαράστασή του? Η απορία είναι εύλογη, αλλά η απάντηση είναι αρνητική. Ο τρόπος και η μορφή που μπορεί να αποθηκευτεί μία πληροφορία σε έναν ηλεκτρονικό υπολογιστή ποικίλει. Αντί να εξετάσουμε πως αποθηκεύει το youtube τα βίντεο του στις βάσεις δεδομένων του, ας παρατηρήσουμε το εξής. Το ίδιο βίντεο του youtube μπορούμε να το δούμε και μέσω flash player αλλά και μέσω HTML5. Οι δύο αυτές μορφές αποτελούν διαφορετικές αναπαραστάσεις του ίδιου βίντεο. Αν το youtube χρησιμοποιούσε για κάθε αναπαράσταση ένα αντίγραφο στην βάση δεδομένων, τότε θα χρειαζόταν τόσο χώρο, όσο δύο φορές το μέγεθος των βίντεο του. Προφανώς κάτι τέτοιο δεν συμβαίνει.

Ένα άλλο παράδειγμα πολλαπλών αναπαραστάσεων είναι το μενού ενός εστιατορίου. Το εστιατόριο μπορεί να παρουσιάζει τον πόρο ”μενού”, στις διάφορες εφαρμογές Κεφάλαιο 2. Υπόβαθρο 8

που το ζητάνε, με αναπαραστάσεις όπως HTML, XML, JSON, CSV ή απλό κείμενο. Πάντα θα παρουσιάζει το ίδιο μενού με τα ίδια προϊόντα. Απλώς κάθε φορά θα τα παρουσιάζει με διαφορετικό τρόπο. Είναι σα να διατηρεί καταλόγους διαφορετικού στυλ για λόγους αισθητικής. Με την διαφορά ότι στον Παγκόσμιο Ιστό το διακύβευμα δεν είναι η αισθητική, αλλά η συμβατότητα με τις εφαρμογές μέσω των διαφορετικών αναπαραστάσεων.

Η τελευταία αυτή πρόταση μας δίνει το έρεισμα να ξανά αναφερθούμε στον Παγκόσμιο Ιστό ως πλατφόρμα εφαρμογών. Προκειμένου να βελτιωθεί ο Παγκόσμιος Ιστός ως πλατφόρμα εφαρμογών είναι απαραίτητο να είναι φιλικός στις εφαρμογές. Συνεπώς διαπιστώθηκε ότι πρέπει να γίνει προσεκτική επιλογή του είδους και του πλήθους αναπαραστάσεων. Η διαπίστωση αυτή συνδέεται με την χαοτική διάσταση του Παγκόσμιου Ιστού. Αν κάθε προγραμματιστής εφαρμογής δημιουργούσε τις δικές του αναπαραστάσεις, όπως του επιτρέπεται, τότε η επικοινωνία εφαρμογών διαφορετικών προγραμματιστών θα ήταν δύσκολη έως αδύνατη. Άρα αυτόματα εμφανίζεται ή ανάγκη καθιέρωσης κάποιων συγκερκιμένων αναπαραστάσεων κοινής αποδοχής (επιλογή πλήθους). Το αμέσως επόμενο ερώτημα είναι ποιες αναπαραστάσεις θα επιλεγούν (επιλογή είδους). Παραδείγματος χάρη, μία αναπαράσταση ευρείας αποδοχής σήμερα είναι η JSON.

2.1.2.4 Πρωτόκολλο HTTP

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

Το HTTP λειτουργεί ως πρωτόκολλο ερωταπαντήσεων και βασίζεται στο μοντέλο πελάτη- εξυπηρετητή (client-server). Προκειμένου να γίνει κατανοητό αυτό, ας υποθέσουμε ότι θέλουμε να επικοινωνήσουν δύο εφαρμογές μεταξύ τους. Σε έναν υπολογιστή εκτελείται μία εφαρμογή την οποία ονομάζουμε πελάτη. Σε έναν άλλο υπολογιστή εκτελείται μία εφαρμογή που την ονομάζουμε εξυπηρετητή. Σχεδιάσαμε αυτές τις εφαρμογές έτσι, ώστε ο εξυπηρετητής να εξυπηρετεί τα αιτήματα του πελάτη. Αφού ο πελάτης αποφασίσει ποιες πληροφορίες χρειάζεται από τον εξυπηρετητή, χρησιμοποιεί το πρωτόκολλο HTTP, ώστε να του μεταδώσει αυτό το αίτημα (request). Ο εξυπηρετητής εξετάζει το αίτημα του πελάτη και του στέλνει σχετική απάντηση (response) πάλι μέσω του πρωτοκόλλου HTTP (εικόνα 2.3). Η διαδικασία αυτή εξηγεί την έννοια πρωτόκολλο ερωταπαντήσεων βασισμένο στο μοντέλο πελάτη-εξυπηρετητή. Η επικοινωνία μέσω HTTP περιορίζεται σε συγκεκριμένες μεθόδους ή αλλιώς ρήματα. Τα ρήματα αυτά αντιστοιχούν σε τύπους αιτημάτων του πελάτη προς τον εξυπηρετητή. Μέχρι σήμερα τα ρήματα αυτά είναι τα εξής [11]: Κεφάλαιο 2. Υπόβαθρο 9

Εικόνα 2.3: Το μοντέλο πελάτη-εξυπηρετητή

• GET - Ανάκτηση resource • POST - Δημιουργία καινούργιου resource • PUT - Αντικατάσταση resource • DELETE - Διαγραφή resource • PATCH - Ενημέρωση resource • OPTIONS - Ανάκτηση διαθέσιμων ρημάτων που υποστηρίζει ο εξυπηρετητής • TRACE - Ανάκτηση του τελικού αποδέκτη του HTTP αιτήματος • HEAD - Ανάκτηση μόνο του header μίας HTTP απάντησης • CONNECT - Σύνδεση μέσω proxy εξυπηρετητή, ο οποίος μπορεί να παίξει τον ρόλο ενός tunnel Ένα αίτημα HTTP από έναν πελάτη σε έναν εξυπηρετητή έχει την παρακάτω μορφή:

Παράδειγμα 2.3: HTTP αίτημα πελάτη σε εξυπηρετητή GET /home.html HTTP/1.1 Host: www.example.org

Βλέπουμε ότι πρόκειται για ένα αίτημα τύπου GET. Κάθε αίτημα απευθύνεται σε έναν εξυπηρετητή. Στην προκειμένη περίπτωση ο εξυπηρετητής είναι ο ”www.example.org”. Επίσης, εφόσον πρόκειται για αίτημα GET, προσδιορίζεται και το resource προς ανάκτηση μέσω του path ”/home.html”. Το path μαζί με τον host και το http scheme (όπως προσδιορίζεται μετά το path στο αίτημα), συνθέτουν το URI του resource.

Η απάντηση του εξυπηρετητή έχει την παρακάτω μορφή:

Παράδειγμα 2.4: HTTP απάντηση εξυπηρετητή σε πελάτη HTTP/1.0 200 OK Content−Type: text/html; charset=UTF−8

Κεφάλαιο 2. Υπόβαθρο 10

The World Wide Web, abbreviated as WWW and commonly known ...

Στην απάντηση ο εξυπηρετητής απαντάει με ”200 OK”, δηλώνοντας ότι το αίτημα διεκπεραιώθηκε επιτυχώς. Το κομμάτι πριν το κενό ονομάζεται header. Ο header περιλαμβάνει τις τεχνικές πληροφορίες της απάντησης. Το κομμάτι μετά το κενό ονομάζεται body. Στο body τοποθετείται η (πιθανή) αναπαράσταση του resource (στην προκειμένη, που ζητήθηκε μέσω GET).

Το ”200 OK” ονομάζεται status code. Το status code αποδίδει συνοπτικά το αποτέλεσμα του αιτήματος. Αποτελείται από ένα νούμερο και ένα σύντομο μήνυμα. Γνωστά status codes είναι π.χ. το ”200 OK”, ”404 Not Found” και το ”500 Internal Server Error”. Τα status codes είναι προκαθορισμένα από την εκάστοτε τυποποίηση του HTTP [15], αλλά υποστηρίζονται και διαφορετικά είδη. Τα status codes είναι χρήσιμα για τους ανθρώπους. Ένας προγραμματιστής μπορεί να σχεδιάσει την Web εφαρμογή του έτσι ώστε αυτή να τα καταλαβαίνει και να δρα ανάλογα.

Μέχρι στιγμής είδαμε πώς ο Παγκόσμιος Ιστός πήρε την σημερινή του μορφή και αναδείξαμε την προγραμματιστική του φύση. Αναλύσαμε επίσης τις αρχιτεκτονικές του αρχές οι οποίες έπαιξαν καθοριστικό ρόλο στην εξάπλωσή του. Όχι όμως μόνο στην εξάπλωσή του αλλά και στην καθιέρωσή του ως πλατφόρμα εφαρμογών. Οι τέσσερις αυτές αρχές (resources, resource representations, URIs και HTTP) αποτελούν ένα κατανοητό σετ εργαλείων, μία βάση, μία πλατφόρμα, πάνω στην οποία μπορούμε να αναπτύξουμε εφαρμογές Παγκόσμιου Ιστού. Με τις τέσσερις αυτές αρχιτεκτονικές στο μυαλό, μπορούμε να εξετάσουμε πως ο Παγκόσμιος Ιστός μπορεί να βελτιωθεί, ώστε να είναι πιο φιλικός στην ανάπτυξη εφαρμογών.

2.1.3 Διδακτορική Διατριβή Roy Fielding

Το Representational State Transfer (REST) είναι ένα σετ κανόνων. Οι κανόνες αυτοί οριοθετούν και προσδιορίζουν το αρχιτεκτονικό στυλ σχεδιασμού ενός υπολογιστικού συστήματος το οποίο ανταλλάσσει πληροφορίες μέσω ενός δικτύου. Αν η αρχιτεκτονική του συστήματος ακολουθεί αυτούς τους κανόνες, τότε η αρχιτεκτονική θεωρείται RESTful, άρα πρόκειται για σύστημα REST. Η ιδέα των REST συστημάτων εμφανίζεται μόλις 6 χρόνια από την ίδρυση του Παγκόσμιου Ιστού. Εμπνευστής της ιδέας ήταν ο Roy Thomas Fielding. Ο Fielding σχεδίασε το REST την περίοδο 1996-1999 και παρουσίασε το τελικό του έργο το 2000 στην διδακτορική του διατριβή με τίτλο ”Architectural Styles and the Design of Network-based Soft- ware Architectures” [7]. Όλη η διδακτορική διατριβή είναι ιδιαίτερα επηρεασμένη από την ραγδαία εξέλιξη του Παγκόσμιου Ιστού και την εμφάνιση των φυλλομετρητών την εποχή εκείνη. Αξιοσημείωτο είναι το γεγονός ότι ο Roy Fielding, ταυτόχρονα με το REST, συμμετείχε με κεντρικό ρόλο στην ανάπτυξη μιας τυποποιημένης εκδοχής του πρωτοκόλλου HTTP. Πρόκειται για τις εκδόσεις 1.0 και 1.1 του HTTP. Η μεγάλη αποδοχή του Παγκόσμιου Ιστού ανέδειξε την ανάγκη να υπάρχει ένα κοινό σχεδιαστικό σημείο αναφοράς, για όλους τους ανθρώπους που ανέπτυσσαν λογισμικό τον Παγκόσμιο Ιστό (και Κεφάλαιο 2. Υπόβαθρο 11

άρα χρησιμοποιούσαν το πρωτόκολλο HTTP). Ο Roy Fielding προκειμένου να πετύχει αυτό το κοινό σημείο αναφοράς, χρησιμοποίησε το REST, ώστε να εντοπίσει τα προβλήματα στην υπάρχουσα έκδοση του HTTP. Αφού τα εντόπισε, σχεδίασε την νέα έκδοση του HTTP με τέτοιον τρόπο ώστε να συνάδει με την φιλοσοφία του REST. Υπό αυτή την έννοια το HTTP/1.1 είναι RESTful. Το REST όμως, παρά τον ισχυρό δεσμό του με το HTTP, δεν αφορά μόνο συστήματα Παγκόσμιου Ιστού. Τεχνικά μιλώντας, οι κανόνες REST μπορούν να αξιολογήσουν οποιοδήποτε σύστημα το οποίο ανταλλάσσει πληροφορίες μέσω ενώς δικτύου. Σήμερα, παρ΄ όλο που έχουν περάσει πάνω από 15 χρόνια από την αρχική ιδέα, τα REST συστήματα έχουν επικρατήσει έναντι όλων των ανταγωνιστών τους. Η λογική REST παραμένει σύγχρονη και αξιοποιείται συστηματικά από την σημερινή βιομηχανία λογισμικού για τον σχεδιασμό υπηρεσιών Παγκόσμιου Ιστού. Στην συνέχεια παραθέτουμε τις παρακάτω προϋποθέσεις ή περιορισμούς που ορίζει ο Fielding στο κεφάλαιο 5 της διατριβής του και που ένα REST σύστημα πρέπει να ακολουθεί:

• Εξυπηρετητής - Πελάτης (Client - Server) Ένα σύστημα REST πρέπει να ακολουθεί το μοντέλο πελάτη-εξυπηρετητή. Ο διαχωρισμός του πελάτη από τον εξυπηρετητή σημαίνει διαχωρισμός της διεπαφής χρήστη από την αποθήκευση των δεδομένων. Έτσι μπορούμε να αναπτύξουμε αυτά τα δύο συστήματα ξεχωριστά: μπορούμε να κατασκευάσουμε την διεπαφή για διάφορες πλατφόρμες (portability) και να βελτιώσουμε την κλιμάκωση του συστήματος απλοποιώντας τα κομμάτια του εξυπηρετητή (scalability).

Εικόνα 2.4: REST: Client-Server [7]

• Κατάσταση πελάτη ανεξάρτητη από τον εξυπηρετητή (Stateless) Ο πελάτης οφείλει να στέλνει στον εξυπηρετητή όλη την πληροφορία που απαιτείται ώστε να γίνει το αίτημά του κατανοητό. Δεν προβλέπεται ο εξυπηρετητής να αποθηκεύει δεδομένα για την κατάσταση του πελάτη. Ως εκ τούτου ο πελάτης δεν πρέπει να αναμένει τέτοια συμπεριφορά. Αυτό έχει το πλεονέκτημα ότι ελαφρύνει το φορτίο του εξυπηρετητή. Ταυτόχρονα όμως αυτό καθίσταται εφικτό με την επιπρόσθετη φόρτωση της δικτυακής κίνησης (λόγω του overhead που εισάγει ο περιορισμός). Περαιτέρω ο εξυπηρετητής δεν έχει έλεγχο της συμπεριφοράς του πελάτη.

• Δυνατότητα αξιοποίησης μηχανισμών γρήγορης ανάκτησης (Cache) Οι απαντήσεις ενός εξυπηρετητή πρέπει υποχρεωτικά να προσδιορίζουν αν είναι cachable ή non-cachable. Δηλαδή αν μπορούν να ανακτηθούν ξανά με γρήγορο τρόπο. Αν μπορούν, τότε ένα cache το οποίο έχει τοποθετηθεί στην μεριά του πελάτη, έχει το δικαίωμα να αποθηκεύσει τα δεδομένα της απάντησης και να τα στείλει στον πελάτη Κεφάλαιο 2. Υπόβαθρο 12

Εικόνα 2.5: REST: Stateless [7]

εφόσον αυτός τα ξαναζητήσει. Έτσι πετυχαίνουμε και γρηγορότερες απαντήσεις και αποσυμφόρηση φορτίου από τον εξυπηρετητή.

Εικόνα 2.6: REST: Cache [7]

• Ομοιόμορφη Διεπαφή (Uniform Interface) Η ομοιόμορφη διεπαφή είναι ένα βασικό στοιχείο του REST. Η ομοιόμορφη διεπαφή ορίζει ότι όλα τα συστήματα σε ένα δίκτυο επικοινωνούν και συνεργάζονται με τον ίδιο τρόπο. Τα συστήματα μπορούν να βασίζονται στο γεγονός ότι η διεπαφή θα παραμείνει ως έχει, όντας ομοιόμορφη, και να αναπτύσσονται ανεξάρτητα το ένα από το άλλο. Έτσι και βελτιώνεται η απλότητα του συνολικού συστήματος και ενθαρρύνεται η εξέλιξη των επί μέρους συστημάτων. Το αντάλλαγμα είναι ότι μειώνεται οι αποδοτικότητα των εφαρμογών που έχουν ειδικές ανάγκες (μη καλυπτόμενες από την ομοιόμορφη διεπαφή). Προκειμένου να επιτευχθεί το Uniform Interface ο Fielding ορίζει τέσσερις επιπρόσθετους περιορισμούς στον σχεδιασμό της διεπαφής: 1. Δυνατότητα ταυτοποίησης/αναγνώρισης των resources 2. Επεξεργασία των resources μέσω resource represenations 3. Τα μηνύματα μεταξύ πελάτη-εξυπηρετητή πρέπει να περιγράφουν τα ίδια το νόημά τους 4. Hypermedia As The Engine Of Application State - HATEOAS Κεφάλαιο 2. Υπόβαθρο 13

Εικόνα 2.7: REST: Uniform Interface (orb σημαίνει object request broker) [7]

• Σύστημα Πολλών Επιπέδων (Layered System) Ο περιορισμός αυτός ορίζει ότι το συνολικό σύστημα θα χωρίζεται σε επίπεδα. Τα επίπεδα αφορούν την πληροφορία που θα διατηρούν. Μέσω των επιπέδων μπορούν να διατηρούνται παλιότερες υπηρεσίες του συστήματος που αφορούν μόνο τους παλιότερους πελάτες. Επίσης μέσω της διαβάθμισης μοιράζεται τόσο το επεξεργαστικό όσο και το δικτυακό φορτίο. Η διαβάθμιση μπορεί να προκαλέσει θέματα απόκρισης και overhead. Για να αντιμετωπιστεί αυτό μπορεί να αξιοποιηθεί περαιτέρω ο περιορισμός που αφορά το caching.

Εικόνα 2.8: REST: Layered System [7]

• Διάθεση κώδικα ύστερα από αίτημα (Code-on-Demand) - προεραιτικό Ο περιορισμός αυτός προβλέπει την δυνατότητα του πελάτη να ”κατεβάζει” και να εκτελεί κώδικα από τον εξυπηρετητή. Με αυτό τον τρόπο μειώνεται το πλήθος των χαρακτηριστικών που πρέπει να σχεδιαστούν για τον πελάτη και άρα η συνολική του πολυπλοκότητα. Ο περιορισμός είναι προεραιτικός με την έννοια ότι σχεδιάζουμε με βάση αυτόν, αλλά ενδεχομένως να μην τον χρησιμοποιούμε σε κάποιες περιπτώσεις. Κεφάλαιο 2. Υπόβαθρο 14

Εικόνα 2.9: REST [7]

2.1.4 Ο Παγκόσμιος Ιστός ως πλατφόρμα εφαρμογών

Όπως συμβαίνει με όλα τα συστήματα ευρείας αποδοχής, έτσι και με τον Παγκόσμιο Ιστό: τα δομικά του στοιχεία συνεχώς απλοποιούνται. Η απλοποίηση αυτή στοχεύει στην εύρεση και την υλοποίηση χαρακτηριστικών, που αφορούν και εξυπηρετούν τους περισσότερους δυνατούς χρήστες του συστήματος. Στην περίπτωση του Παγκόσμιου Ιστού χρήστες είναι και οι προγραμματιστές εφαρμογών, έμμεσα. Έτσι η απλοποίηση των δομικών στοιχείων του Παγκόσμιου Ιστού στοχεύει και στην διευκόλυνση των προγραμματιστών εφαρμογών. Υπό αυτή την έννοια έχει διαμορφωθεί το εξής σχεδιαστικό μοντέλο στον Παγκόσμιο Ιστό: οι σχεδιαστές των διαφόρων πρωτοκόλλων και εννοιών στοχεύουν τους προγραμματιστές και οι τελευταίοι αναλαμβάνουν την ”κατά τον χρήστη” σχεδίαση εφαρμογών. Άρα η σχεδίαση σε πρώτο επίπεδο (τεχνικό), αφορά όσους εμπλέκονται στον σχεδιασμό εφαρμογών (Web Applications) ή υπηρεσιών (Web Services) Παγκόσμιου Ιστού. Έτσι ο Tim Berners-Lee, ο Roy Fielding και πολύ άλλοι, σχεδίαζαν πάντα πρώτα για τον μηχανικό λογισμικού. Συνεπώς ο Παγκόσμιος Ιστός, το πρωτόκολλο HTTP και τα συστήματα REST έχουν σχεδιαστεί με βασικό μέλημα τον μηχανικό λογισμικού. Έχουμε ήδη αναλύσει τα URIs, τους πόρους, τις αναπαραστάσεις και το http. Δύο ακόμη βασικά στοιχεία που διέπουν τον Παγκόσμιο Ιστό σήμερα και συνεισφέρουν στην ανάπτυξη εφαρμογών είναι η έννοια HATEOAS και η έννοια της ομοιόμορφης διεπαφης.

2.1.4.1 Hypermedia as the engine of application state - HATEOAS

Η έννοια hypermedia as the engine of the application state, είναι μία έννοια η οποία επίσης πρωτοεμφανίστηκε στην διδακτορική διατριβή το Roy Fielding. Πρόκειται για μία έννοια η οποία αποτελεί βασικό δόγμα του μοντέλου REST, παρ’ όλο που δεν αναφέρεται ρητά ως μία από τις 6 σχεδιαστικές αρχές του (βρίσκεται εντός του 4ου περιορισμού Uniform Interface). Αποτελεί βασικό σημείο σύγχυσης των μηχανικών λογισμικού και ενδεχομένως την πιο πολύπλοκη ή αμφιλεγόμενη έννοια από μία κατά τα άλλα απλή φιλοσοφία.

Καθώς πλοηγούμαστε στον Παγκόσμιο Ιστό, έχουμε συνηθίσει να επιλέγουμε Κεφάλαιο 2. Υπόβαθρο 15

υπερσυνδέσμους και να συμπληρώνουμε φόρμες. Οι ενέργειες αυτές μας οδηγούν σε νέες επιλογές: νέους υπερσυνδέσμους ή/και νέες φόρμες προς συμπλήρωση. Αυτό που συμβαίνει στην πραγματικότητα είναι ότι ακολουθούμε ένα πρωτόκολλο, μία διαδικασία, ώστε να πετύχουμε έναν τελικό σκοπό. Ένα πολύ κλασσικό παράδειγμα πρωτοκόλλου είναι η παραγγελία ενός προϊόντος από ένα ηλεκτρονικό κατάστημα, όπως το Amazon5. Το πρωτόκολλο είναι εμφανές: Βρίσκουμε ένα προϊόν, το προσθέτουμε στο καλάθι, επιλέγουμε checkout, προσθέτουμε στοιχεία αποστολής, επιλέγουμε τρόπο πληρωμής, πληρώνουμε και η παραγγελία μας επικυρώνεται. Το Amazon μας καθοδηγεί κατά την διαδικασία αυτή με υπερσυνδέσμους. Με την ίδια λογική το Facebook μας καθοδηγεί στην ανάρτηση ενός post, το Youtube στον σχολιασμό ενός βίντεο, η τοπική ηλεκτρονική εφημερίδα στην ανάγνωση ενός άρθρου και η πανεπιστημιακή πλατφόρμα στην υποβολή μιας εργασίας. Όλες αυτές οι διαδικασίες αποτελούνται από μία σειρά βημάτων. Η μετάβαση σε κάθε επόμενο βήμα πραγματοποιείται με την βοήθεια υπερσυνδέσμων. Κάθε επιλογή υπερσυνδέσμου οδηγεί σε νέα κατάσταση της εφαρμογής. Αυτό είναι η έννοια του υπερμέσου (hypermedia): Η μετάβαση από τον ένα υπερσύνδεσμο στον άλλο οδηγεί στην αλλαγή της κατάστασης της εφαρμογής (application state). Έτσι στην παραγγελία μεταβαίνουμε από την κατάσταση ”έχω γεμίσει το καλάθι αγορών” στην ”πληρώνω τα προϊόντα που επέλεξα”. Τα πρωτόκολλα των διάφορων διαδικασιών μπορεί να γίνουν περισσότερο πολύπλοκα: μπορούμε να προσθέσουμε κι άλλα προϊόντα αφού επιλέξουμε ”checkout”, μπορούμε να ακυρώσουμε την παραγγελία, να επεξεργαστούμε το σχόλιο, να ανεβάσουμε νέα έκδοση της εργασίας κ.λ.π.. Η πολυπλοκότητα των πρωτοκόλλων οδήγησε στα Domain Application Protocols ή DAP. Δηλαδή πρωτόκολλα που αφορούν ένα συγκεκριμένο επιχειρησιακό αντικείμενο (domain). Αυτό σημαίνει ότι τα πρωτόκολλα των επιχειρήσεων, των φορέων και των οργανισμών είναι ειδικά (από τεχνικής άποψης). Έτσι πρέπει η καθοδήγηση του χρήστη να είναι σαφής και απλή. Η καθοδήγηση επιτυγχάνεται με το HATEOAS. Το HATEOAS είναι η τεχνική έκδοση του DAP. Κατά HATEOAS η εκάστοτε εφαρμογή παρέχει μόνο ένα endpoint, δηλαδή ένα σημείο εισαγωγής στο σύστημα. Η περαιτέρω πλοήγηση καθίσταται δυνατή μέσω των hypermedia. Το endpoint είναι το μόνο που χρειάζεται να ξέρει η εφαρμογή, ώστε να μπορέσει να πλοηγηθεί. Το endpoint δεν είναι άλλο από ένα αρχικό URI.

Ας διευκρινίσουμε τι σημαίνει κατάσταση εφαρμογής. Αν εφαρμογή σημαίνει πρόγραμμα ηλεκτρονικού υπολογιστή με συγκεκριμένο στόχο, τότε πρωτόκολλο εφαρμογής είναι μία ακολουθία βημάτων που οδηγούν σε αυτό τον στόχο. Κατάσταση της εφαρμογής είναι ένα στιγμιότυπο αυτού του πρωτοκόλλου. Κατά HATEOAS, οι μεταβάσεις στην επόμενη κατάσταση διαφημίζονται στις απαντήσεις του εξυπηρετητή προς τον πελάτη (HTTP απαντήσεις). Έτσι ο πελάτης μπορεί να επιλέξει σε πια επόμενη κατάσταση θέλει να μεταβεί, αφού διαβάσει την απάντηση του εξυπηρετητή. Εδώ πρέπει να επισημάνουμε ότι οι υπερσύνδεσμοι που παρουσιάζονται στον πελάτη είναι τρέχουσες καταστάσεις πόρων και όχι εφαρμογής. Η κατάσταση εφαρμογής είναι το σύνολο των καταστάσεων των πόρων του παρουσιάζονται (πιθανόν και από παραπάνω από μία υπηρεσίες του ίδιου εξυπηρετητή). Ας το εξηγήσουμε αυτό με το παρακάτω παράδειγμα [31]:

Παράδειγμα 2.5: Απάντηση εξυπηρετητή με Hypermedia Control HTTP/1.1 200 OK Content−Length: 342 Content−Type: application/xml Date: Sun, 21 Mar 2010 17:04:10 GMT

5https://www.amazon.com/ Κεφάλαιο 2. Υπόβαθρο 16

2.0 Michael Faraday 11223344 12 12

Το παραπάνω αποτελεί κομμάτι της HTTP απάντησης μίας υποθετικής καφετέριας που λειτουργεί στον Παγκόσμιο Ιστό. Συγκεκριμένα είναι απάντηση η οποία στέλνεται στον πελάτη, αφού παραγγείλει και πληρώσει το προϊόν. Στην απάντηση εμφανίζονται δύο νέοι για τον πελάτη υπερσύνδεσμοι (μπλε χρώμα). Ένας που οδηγεί στην παρακολούθηση της εξέλιξης της παραγγελίας του και ένας που οδηγεί στην έκδοση απόδειξης. Οι πόροι εδώ είναι η παραγγελία και η απόδειξη. Οι σύνδεσμοι των πόρων αυτών αντιπροσωπεύουν την τρέχουσα κατάστασή τους (resource state). Το resource ”receipt” μόλις δημιουργήθηκε και το resource ”order” βρίσκεται στην κατάσταση διεκπεραίωσης. Οι δύο σύνδεσμοι μαζί αντιπροσωπεύουν την τρέχουσα κατάσταση της εφαρμογής (application state). Η εφαρμογή εδώ είναι η διαδικασία παραγγελίας της καφετέριας και βρίσκεται στην κατάσταση ολοκληρωμένης πληρωμής. Η καθοδήγηση του πελάτη (client) με hypermedia είναι η έννοια ”μηχανή” (”engine”) του HATEOAS. Οι hypermedia μηχανές σχεδιάζονται τόσο για αξιοποίηση από εφαρμογές, όσο και από ανθρώπους. Όταν η καθοδήγηση αφορά εφαρμογές, τότε πρόκειται για αυτόνομες εφαρμογές. Δηλαδή εφαρμογές που μπορούν να πλοηγούνται σε υπηρεσίες του Παγκόσμιου Ιστού χωρίς την ανθρώπινη παρέμβαση. Τέτοιες εφαρμογές παραδείγματος χάρη αναπτύσσουν οι μηχανές αναζήτησης. Η σύγχυση που επικρατεί γύρω από την χρησιμότητα του HATEOAS, έχει να κάνει με το πώς αυτό υλοποιείται. Οι προγραμματιστές εφαρμογών Παγκόσμιου Ιστού προτιμούν να διαβάζουν το documentation της υπηρεσίας, το οποίο περιγράφει όλο το DAP. Έτσι γνωρίζουν εκ των προτέρων τις μεταβάσεις (hypermedia). Άρα δεν σχεδιάζουν εφαρμογές που τις ανακαλύπτουν καθώς πλοηγούνται στην υπηρεσία. Δηλαδή η καθοδήγηση δεν γίνεται από τα hypermedia αλλά από τον προγραμματιστή, σχεδιαστικά. Αντίθετα ο Roy Fielding προσδιορίζει ότι το μόνο που πρέπει να ξέρει ο πελάτης, είναι τα είδη των αναπαραστάσεων που χρησιμοποιεί η υπηρεσία για τους πόρους της. Επειδή όμως δεν περιγράφεται στην διδακτορική του διατριβή τι σημαίνει αυτό πρακτικά, η σωστή υλοποίηση REST συστημάτων αποτελεί σχεδιαστική πρόκληση.

Στο σημείο αυτό πρέπει να αναφέρουμε και το Richardson Maturity Model [31]. Κατά το μοντέλο αυτό ο Richardson αξιολογεί τις διάφορες υπηρεσίες Παγκόσμιου Ιστού πόσο REST είναι. Το Richardson Maturity Model φαίνεται στην εικόνα 2.10. Σύμφωνα με το μοντέλο αυτό στο επίπεδο 0 είναι οι RPC-Style αρχιτεκτονικές, στο επίπεδο 1 οι αρχιτεκτονικές που εισάγουν resources, στο επίπεδο 2 αυτές που λειτουργούν και με Uniform Interface και τέλος REST αυτές που αξιοποιούν και το HATEOAS. Κεφάλαιο 2. Υπόβαθρο 17

Εικόνα 2.10: Το Richardson Maturity Model6

2.1.4.2 Ομοιόμορφη Διεπαφή - Uniform Interface στον Παγκόσμιο Ιστό

Ομοιόμορφη Διεπαφή στον Παγκόσμιο Ιστό σημαίνει, όλες οι μέθοδοι της διεπαφής να έχουν κοινή ερμηνεία για τις εφαρμογές. Στον Παγκόσμιο Ιστό το πρωτόκολλο εφαρμογών είναι το HTTP. Έτσι οι μέθοδοι της διεπαφής είναι οι μέθοδοι του HTTP. Κατά την Ομοιόμορφη Διεπαφή, πρέπει οι HTTP μέθοδοι να έχουν κοινή ερμηνεία για όλους. Κατά REST δεν απαιτείται η ερμηνεία αυτή να είναι ας πούμε ο ορισμός των μεθόδων HTTP του Tim Berners-Lee. Η πραγματική απαίτηση είναι όλες οι υπηρεσίες Παγκόσμιου Ιστού να χρησιμοποιούν τις μεθόδους του HTTP με τον ίδιο τρόπο. Για παράδειγμα το ευρέως διαδεδομένο ρήμα GET, να σημαίνει για όλους ”ανάκτηση πόρου”. Να μην εμφανίζονται δηλαδή αιτήματα του στυλ

GET ../method=flickr.photos.delete

το οποίο διαγράφει το resource φωτογραφία. Ρήμα το οποίο έχει περισσότερο την ανάγκη συμβάσεως είναι το POST, το οποίο χρησιμοποιείται για αποστολή δεδομένων. Μία γνωστή σύμβαση για τα ρήματα POST, GET, PUT, DELETE είναι η Create Read Update Delete ή CRUD. Πρόκειται για μία σύμβαση που εμφανίστηκε στα συστήματα αρχειοθέτησης των λειτουργικών συστημάτων (file systems) και αφορά την δημιουργία, την ανάγνωση, την επεξεργασία και την διαγραφή αρχείων. Κατά την σύμβαση αυτή τα 4 ρήματα του Παγκόσμιου Ιστού παίρνουν την παρακάτω σημασία: • POST: Δημιουργία resource • GET: Ανάκτηση resource • PUT: Ενημέρωση/Επεξεργασία resource • DELETE: Διαγραφή resource Επιπρόσθετα Ομοιόμορφη Διεπαφή στο HTTP σημαίνει ότι και οι απαντήσεις θα είναι επεξηγηματικές για τον πελάτη. Δηλαδή τα status codes θα περιέχουν χρήσιμη

6http://martinfowler.com/articles/richardsonMaturityModel.html Κεφάλαιο 2. Υπόβαθρο 18

Verb Safe Idempotent POST GET PUT DELETE

Πίνακας 2.1: Safety & Idempotency των POST, GET, PUT, DELETE

πληροφορία, βάση της οποίας ο πελάτης θα αντιλαμβάνεται την κατάσταση του εξυπηρετητή και θα μπορεί να αποφασίσει τα επόμενα βήματά του. Τέλος κατά τον σχεδιασμό του REST συστήματος ο μηχανικός πρέπει να λαμβάνει υπ’ όψιν και τις ιδιότητές των HTPP verb ως προς την ασφάλεια (safety) και την δυνατότητα επανάληψης του αιτήματος χωρίς να προκληθεί περαιτέρω αλλαγή (idempotency). Το safety αφορά το πόσο επηρεάζει τον εξυπηρετητή το αίτημα του verb ενώ το idempotency το αν η επανάληψή του αιτήματος προκαλεί αλλαγές. Στον πίνακα 2.1 συνοψίζονται ποία από τα POST, GET, PUT, DELETE είναι safe ή idempotent.

2.1.5 RESTful Web APIs & OpenAPI Specification

Η αποδοχή των RESTful υπηρεσιών στον Παγκόσμιο Ιστό σήμερα είναι μεγάλη. Η τεχνολογία REST επικράτησε και όλο και περισσότεροι πάροχοι υπηρεσιών Παγκόσμιου Ιστού την αξιοποιούν. Η διάθεση των υπηρεσιών προς το κοινό και τους προγραμματιστές εφαρμογών, γίνεται μέσω των RESTful Web APIs.

2.1.5.1 APIs

API σημαίνει Application Programming Interface ή Διεπαφή Προγραμματισμού Εφαρμογών. Ας εξετάσουμε το εξής παράδειγμα για να συλλάβουμε αυτή την έννοια. Σε ένα αυτοκίνητο, ο κατασκευαστής παρέχει στον οδηγό τιμόνι, κιβώτιο ταχυτήτων, πεντάλ, κουμπιά, καντράν. Μέσω του τιμονιού ο οδηγός στέλνει οδηγίες στους τροχούς, ενώ το καντράν λαμβάνει σήματα από την μηχανή. Αντίστοιχα τα διάφορα κουμπιά στέλνουν εντολές στο ηλεκτρονικό σύστημα του αυτοκινήτου. Σίγουρα κάποιος δεν μπορεί να χρησιμοποιήσει όλα αυτά τα χαρακτηριστικά αν δεν έχει δίπλωμα οδήγησης. Δεν χρειάζεται όμως να είναι μηχανικός αυτοκινήτων για να οδηγήσει το αυτοκίνητο. Αυτό διότι ο κατασκευαστής έχει φροντίσει να παρέχει στον οδηγό μία αφαιρετική αναπαράσταση των εσωτερικών συστημάτων του αυτοκινήτου. Η αναπαράσταση είναι το τιμόνι, τα πεντάλ, το κιβώτιο ταχυτήτων, το καντράν, τα κουμπιά, τα χερούλια. Έτσι ο οδηγός αρκεί μόνο να γνωρίζει, πώς να χειρίζεται (μέσω διπλώματος και manuals) αυτή την αναπαράσταση. Αυτή η αφαιρετική αναπαράσταση στον προγραμματισμό είναι το Ap- plication Programming Interface. Τα APIs αφορούν υπολογιστικά συστήματα. Δεδομένου ενός συστήματος, το API αποτελεί μία εργαλειοθήκη του. Η εργαλειοθήκη αυτή έχει δυνατότητα να χρησιμοποιεί κάποιες από τις λειτουργίες του συστήματος. Μάλιστα έχει σχεδιαστεί με τέτοιο τρόπο, ώστε να είναι εύχρηστη και εξυπηρετεί ένα συγκεκριμένο πεδίο εφαρμογής του συστήματος. Ένας προγραμματιστής μπορεί να αναπτύξει εφαρμογές λογισμικού αξιοποιώντας το API. Όπως ο οδηγός αυτοκινήτου δεν χρειάζεται να ξέρει να τις τεχνικές λεπτομέρειες του αυτοκινήτου, έτσι και ο προγραμματιστής δεν χρειάζεται να ξέρει τις τεχνικές λεπτομέρειες του συστήματος. Αν δεν υπήρχε το API, τότε θα έπρεπε ο προγραμματιστής Κεφάλαιο 2. Υπόβαθρο 19

να το αναπτύξει μόνος του, αφού πρώτα μελετούσε προσεκτικά το σύστημα. Ας εξετάσουμε και το παρακάτω παράδειγμα: Ένας σχεδιαστής λογισμικού σχεδιάζει ένα πολύ καλό και σύνθετο λογισμικό το οποίο μπορεί να πραγματοποιεί αγοραπωλησίες και άλλες ενέργειες σε διεθνή χρηματιστήρια. Ένας άλλος προγραμματιστής θέλει να αναπτύξει μία εφαρμογή που πραγματοποιεί στατιστική ανάλυση σε δεδομένα χρηματιστηρίων. Ένας τρίτος προγραμματιστής θέλει να σχεδιάσει έναν αυτόνομο πράκτορα που πραγματοποιεί μόνος του αγοραπωλησίες. Ένας τέταρτος θέλει να φτιάξει μία ιστοσελίδα που να δείχνει σε πραγματικό χρόνο όλους τους δείκτες των χρηματιστηρίων συγκεντρωμένους. Ας υποθέσουμε ότι οι τρεις τελευταίοι προγραμματιστές είναι μεγάλες εταιρείες. Όπως επίσης ότι υπάρχουν και πολλές άλλες εταιρείες με τις δικές τους ιδέες και συγκεκριμένες υλοποιήσεις. Όλα αυτά τα ενδιαφερόμενα μέρη (stakeholders), θα τα εξυπηρετούσε να μπορούν να αξιοποιήσουν το καλό λογισμικό του πρώτου προγραμματιστή λόγω κόστους, χρόνου και τεχνογνωσίας. Ο πρώτος προγραμματιστής αντιλαμβάνεται αυτό το ενδιαφέρον για το λογισμικό του και αποφασίζει να δώσει την δυνατότητα στους προγραμματιστές των εταιρειών να το χρησιμοποιήσουν. Επειδή όμως είναι καλός προγραμματιστής και γνωρίζει καλά της αρχές σχεδίασης λογισμικού, διαπιστώνει ότι θα είναι πολύ δύσκολο να αξιοποιήσουν οι άλλοι προγραμματιστές τον κώδικά του. Για παράδειγμα θα εξυπηρετούσε ιδιαίτερα τον προγραμματιστή του αυτόνομου πράκτορα αν υπήρχε μία συνάρτηση της μορφής buy('NASDAQ', 'GOOGL', targetPrice)

αντί μία ακολουθία εντολών connectToken = connectStockExchange('NASDAQ') buyOrder = createBuyOrder(connectToken, 'GOOGL', targetPrice) placeBuyOrder(buyOrder,connectToken)

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

Στην περίπτωση του Παγκόσμιου Ιστού, τα APIs χρησιμοποιούνται για να εκθέσουν ένα συγκεκριμένο κομμάτι μιας υπηρεσίας (π.χ. YouTube). Συγκεκριμένα, ο πελάτης (client) της υπηρεσίας, μπορεί να στείλει HTTP αιτήματα μέσω του API στην εκάστοτε υπηρεσία. Ο εξυπηρετητής της υπηρεσίας (server), πάλι μέσω του API στέλνει στον πελάτη την HTTP απάντηση. Ο προγραμματιστής Web εφαρμογών, ενσωματώνει την λογική του API στην εφαρμογή του. Όταν το Web API σχεδιάζεται ακολουθώντας την φιλοσοφία του REST, τότε το API ονομάζεται RESTful Web API. Κεφάλαιο 2. Υπόβαθρο 20

2.1.5.2 OpenAPI Specification

Αφού συγγραφεί ένα RESTful Web API, το επόμενο βήμα είναι να γραφτούν τα λογισμικά του πελάτη και του εξυπηρετητή. Προκειμένου να γίνει αυτό, μαζί με το API συντάσσεται και το λεγόμενο documentation. Το API documentation περιγράφει την λειτουργία του API με κατανοητό προς τον άνθρωπο τρόπο. Δηλαδή περιγράφονται οι πιθανές παράμετροι ενός http αιτήματος, η αναμενόμενη απάντηση, ο σκοπός της αληλεπίδρασης και άλλες τεχνικές λεπτομέρειες που εξαρτώνται από το εκάστοτε API. Οι τεχνικές αυτές πληροφορίες είναι απαραίτητες για την αξιοποίηση του API στον κώδικα του πελάτη. Ταυτόχρονα όμως, όπως εξελίσσεται το λογισμικό έτσι εξελίσσονται και τα APIs. Διορθώνονται προβλήματα, ενσωματώνονται νέες λειτουργίες και αφαιρούνται παλιές. Οι αλλαγές αυτές συνεπάγονται απαραίτητες αλλαγές στο documentation, στην εφαρμογή και στην υπηρεσία. Οι μηχανικοί πρέπει να διαβάσουν το νέο documentation, να εντοπίσουν τις αλλαγές που τους αφορούν και να ενημερώσουν το λογισμικό τους. Η εξέλιξη των API οδηγεί στην ανάγκη τακτικής ενημέρωσης του documentation από τους μηχανικούς του συστήματος. Επιπλέον οι μηχανικοί της υπηρεσίας και της εφαρμογής πρέπει να παρακολουθούν τακτικά την εξέλιξη του API. Αν αυτό δεν γίνεται, τότε οι εφαρμογές που το χρησιμοποιούν είναι δυνατόν να καταστούν μη ανταγωνιστικές ή ακόμη και μη λειτουργικές. Μάλιστα δεδομένου αυτών των χαρακτηριστικών, οι μηχανικοί συστήματος ενδέχεται να ακολουθούν ένα μετριοπαθέστερο μοντέλο εξέλιξης του API. Επειδή όλες αυτές οι επιπλοκές μεταφράζονται σε κόστος, η συνεχώς εξελισσόμενη βιομηχανία λογισμικού επιχείρησε να απλοποιήσει την διαδικασία ανάπτυξης API. Οι διάφοροι μηχανικοί των RESTful Web APIs παρατήρησαν ότι • Οι βασικές αρχές του Παγκόσμιου Ιστού, ο σχεδιασμός του πρωτοκόλλου HTTP και η τεχνολογία REST, προσδίδουν κοινά χαρακτηριστικά στα διάφορα RESTful Web APIs. Έτσι ανεξαρτήτως λειτουργίας όλα τα RESTful Web APIs χρησιμοποιούν HTTP αιτήματα και απαντήσεις, HTTP ρήματα, resources, URIs κ.λ.π.. Συνεπώς, εξ’ αρχής, υπάρχουν τεχνικά χαρακτηριστικά τα οποία δεν διαφέρουν από RESTful Web API σε RESTful Web API • Η εξέλιξη των APIs απαιτεί τον συντονισμό διαφορετικών ομάδων λογισμικού. Δηλαδή της ομάδας ανάπτυξης του API και συγγραφής του documentation, την ομάδα ανάπτυξης της υπηρεσίας και την ομάδα ανάπτυξης της εφαρμογής. Η επικοινωνία αυτή είναι επαρκώς πολύπλοκη ώστε να επηρεάζει το κόστος και την ανταγωνιστικότητα των προϊόντων. Οι παρατηρήσεις αυτές οδήγησαν στην εμφάνιση τυποποιήσεων των RESTful Web APIs. Μία τυποποίηση ενός RESTful Web API, είναι ένα ή περισσότερα τεχνικά έγγραφα, τα οποία περιγράφουν λεπτομερώς την λειτουργία και τα τεχνικά χαρακτηριστικά του. Επίσης η τυποποίηση έχει τέτοια μορφή ώστε να μπορεί να διαβαστεί από λογισμικό (ma- chine readable format). Η πιο δημοφιλής τυποποίηση σήμερα είναι το OpenAPI Speci- fication. Το OpenAPI Specification (γνωστό και ως Swagger) [28] είναι μία κοινή πρωτοβουλία διαφόρων εταιρειών τεχνολογίας (εικόνα 2.11). Η πρωτοβουλία ονομάζεται OpenAPI Ini- tiative7. Στόχος της πρωτοβουλίας είναι η δημιουργία ενός κοινού σημείου αναφοράς για τους μηχανικούς RESTful API. Όλες αυτές οι εταιρείες, αλλά και πολλές άλλες που δεν εμπλέκονται άμεσα με την τυποποίηση, χρησιμοποιούν σε πολύ μεγάλο βαθμό RESTful APIs στην επιχειρηματική τους δραστηριότητα. Ενδεικτική είναι η ερευνά

7https://openapis.org/ Κεφάλαιο 2. Υπόβαθρο 21

της apigee (μία εκ των 18), πάνω στη χρήση των δικών της API για την περίοδο 2014- 20158. Από αυτήν μας ενδιαφέρουν οι δύο πρώτες διαφάνειες (βλ. εικόνες 2.12, 2.13).

Εικόνα 2.11: Οι εταιρείες του OpenAPI Initiative

Εικόνα 2.12: Διαδικτυακή κίνηση κλήσεων API της εταιρείας apigee

Στο πρώτο γράφημα βλέπουμε την συνεχώς αυξανόμενη κίνηση σε όλα τα επίπεδα. Στο δεύτερο προβάλλεται το ενδιαφέρον στοιχείο ότι το μεγαλύτερο κομμάτι της πίτας των ηλεκτρονικών υπηρεσιών αφορά λύσεις B2B (Business to business). Οι εταιρείες αυτές λοιπόν έχουν διαπιστώσει ότι υπάρχει μεγάλη ανάγκη για την καθιέρωση μίας τέτοιας τυποποίησης. Οι δε υπάρχουσες λύσεις δεν αντιμετωπίζουν το πρόβλημά τους, διότι δεν είναι λύσεις κοινής αποδοχής αλλά προϊόν συμβιβασμών μεταξύ κάποιων ενδιαφερόμενων παραγόντων. Αναφέρουμε προϋπάρχουσες τυποποιήσεις στο Παράρτημα B. Το OpenAPI Specification δίνει την δυνατότητα αυτόματης παραγωγής του documen- tation αλλά και του κώδικα της υπηρεσίας και της εφαρμογής. Προφανώς ο κώδικας που παράγεται αφορά μόνο το API και όχι την λειτουργία της εφαρμογής ή του συστήματος. Αξίζει να επισημάνουμε ότι το OpenAPI Specification είναι ανεξάρτητο από την γλώσσα προγραμματισμού στην οποία είναι γραμμένο το εκάστοτε λογισμικό. Επίσης με κατάλληλα εργαλεία δύναται να παραχθούν και τα απαραίτητα τεστ για την δοκιμή του API. Καθώς το API εξελίσσεται, εξελίσσεται και το OpenAPI Specification. Πλέον οι διεργασίες ενημέρωσης των εξαρτώμενων από το Specification συστημάτων, υποστηρίζονται από λογισμικό. Αυτό διότι, όπως είπαμε, το OpenAPI Specification έχει

8https://pages.apigee.com/ebook-State-of-APIs-reg.html?int_source=hpt-main&int_medium=website& int_campaign=ebook&int_content=state-of-apis-report Κεφάλαιο 2. Υπόβαθρο 22

Εικόνα 2.13: Περιπτώσης χρήσης των ηλεκτρονικών υπηρεσιών της apigee machine readable format. Σχολιάζουμε τέλος ότι η ιδέα της τυποποίησης των REST- ful Web APIs, προωθεί ακόμα καλύτερα την ιδέα του Παγκόσμιου Ιστού ως πλατφόρμα εφαρμογών.

2.1.5.3 Τεχνικά χαρακτηριστικά του OpenAPI Specification

Στην υποενότητα αυτή περιγράφουμε συνοπτικά τα τεχνικά χαρακτηριστικά του Ope- nAPI Specification[17]. Επισημαίνουμε ότι την στιγμή συγγραφής της διπλωματικής βρισκόμαστε στο version 2 ενώ ήδη γράφεται το version 3. Το OpenAPI Specification ορίζει ένα σετ αρχείων που περιγράφουν το RESTful API. Η τυποποίηση ορίζει • Την γλώσσα των αρχείων: JSON ή YAML που είναι υπερσύνολο της JSON • Την δομή των αρχείων, κυρίως ότι το βασικό αρχείο ονομάζεται swagger.json και στα υπόλοιπα γίνεται παραπομπή μέσω του keyword $ref • Τα Data Types (εικόνα 2.14) • Το Schema Το Schema αποτελεί το βασικότερο κομμάτι της τυποποίησης. Στο Schema ορίζονται τα ”Objects”. Τα Objects του Schema είναι τα εξής: • Swagger Object • Info Object • Contact Object • License Object • Paths Object • Path Item Object • Operation Object • External Documentation Object • Parameter Object Κεφάλαιο 2. Υπόβαθρο 23

Εικόνα 2.14: Τα Data Types του OAI Specification

• Items Object • Responses Object • Response Object • Headers Object • Example Object • Header Object • Tag Object • Reference Object • Schema Object • XML Object • Definitions Object • Parameters Definitions Object • Responses Definitions Object • Security Definitions Object • Security Scheme Object • Scopes Object • Security Requirement Object Η περιγραφή και το περιεχόμενο του κάθε Object καταγράφεται αναλυτικά στην ιστοσελίδα του OpenAPI Specification στο Github: https://github.com/OAI/ OpenAPI-Specification/blob/master/versions/2.0.md. Πολλά Object σχετίζονται μεταξύ τους ιεραρχικά. Σε ένα OpenAPI Specification αρχείο συναντάμε την παρακάτω κλασσική, ιεραρχική δομή: Κεφάλαιο 2. Υπόβαθρο 24

• Όλες οι πληροφορίες του API που σχετίζονται με την υπηρεσία που το σχεδιάζει αλλά και το ίδιο το API, καταγράφονται στα Info, Contact και License Object στην αρχή του αρχείου. • Στην συνέχεια καταγράφονται όλα τα paths του API, στο Paths Object. • Κάθε path (Path Object) περιέχει τα operation που μπορούν να πραγματοποιηθούν (http verbs όπως GET, POST, PUT, DELETE). • Κάθε operation (Operation Object) με την σειρά του περιέχει τις τεχνικές λεπτομέρειές του. Τέτοιες είναι το http αίτημα και τα τεχνικά του χαρακτηριστικά, η http απάντηση και τα τεχνικά της χαρακτηριστικά, τα τεχνικά χαρακτηριστικά ασφάλειας κ.α.. • Σε κάθε http αίτημα και απάντηση, περιγράφονται οι παράμετροί τους. Δηλαδή περιγράφεται η τοποθεσία των παραμέτρων (π.χ. path, header, body), ο τύπος και η μορφή τους (string, number, integer, csv, file, xml) και πολλές άλλες τεχνικές λεπτομέρειες. Οι περισσότερες από αυτές τις λεπτομέρειες προέρχονται από το JSON Schema9. • Στο τέλος του αρχείου (ή σε άλλα αρχεία) οι διάφορες παράμετροι που εμφανίστηκαν στο Paths Object, οργανώνονται προαιρετικά στο Definitions Object. Μιλώντας με όρους προγραμματισμού, το Definitions Object συγκεντρώνει τις ”μεταβλητές του προγράμματος” ή απλά τα μοντέλα. Η ύπαρξη των definitions αποσκοπεί στο να μην υπάρχουν επαναλήψεις ίδιων ορισμών, αλλά και στην γενικότερη οργανωμένη, ευανάγνωστη, δομή των αρχείων. Παραδείγματα αρχείου OpenAPI Specification φαίνονται στις εικόνες 2.15, 2.16 και 2.17

9http://json-schema.org/latest/json-schema-validation.html Κεφάλαιο 2. Υπόβαθρο 25

Εικόνα 2.15: OpenAPI Specification: Παράδειγμα Definitions

Εικόνα 2.16: OpenAPI Specification: Παράδειγμα πληροφοριών του API Κεφάλαιο 2. Υπόβαθρο 26

Εικόνα 2.17: OpenAPI Specification: Παράδειγμα Paths Object Κεφάλαιο 2. Υπόβαθρο 27

2.2 Behavior-Driven Development

2.2.1 Σχεδιασμός και Ανάπτυξη Λογισμικού

Στην υποενότητα 2.1.1, έγινε μία σύντομη ιστορική αναδρομή στην τεχνολογική εξέλιξη του Παγκόσμιου Ιστού. Μιλήσαμε για τα διάφορα στάδια της επιστήμης και καταλήξαμε στα RESTful APIs υπηρεσιών Παγκόσμιου Ιστού. Ένα στάδιο (επιστημονικά) πριν τα RESTful APIs, είναι τα προγράμματα των υπολογιστών. Πρόγραμμα ηλεκτρονικού υπολογιστή είναι μία ακολουθία εντολών. Οι εντολές αυτές έχουν σκοπό να προγραμματίσουν τον υπολογιστή, έτσι ώστε να εκτελέσει μία επιθυμητή ενέργεια. Σήμερα οι επιθυμητές ενέργειες είναι ολόκληρες επιχειρησιακές διαδικασίες. Η διαδικασία συγγραφής προγραμμάτων λοιπόν έχει και αυτή εξελιχθεί δραματικά όλα αυτά τα χρόνια. Πλέον τα προγράμματα ονομάζονται λογισμικό (software) ο χώρος ονομάζεται Σχεδιασμός και Ανάπτυξη Λογισμικού ή Τεχνολογία Λογισμικού (Software Engineering). Περιλαμβάνει δε πλήθος διαδικασιών και κανόνων, που προσδιορίζουν με την μεγαλύτερη δυνατή σαφήνεια, το πώς σχεδιάζεται και αναπτύσσεται ένα λογισμικό. Το σύνολο αυτών των διαδικασιών και κανόνων ονομάζεται Διαδικασία Ανάπτυξης Λογισμικού [25]. Η σημερινή Διαδικασία Ανάπτυξης Λογισμικού, μπορεί να γενικευθεί στις εξής 7 βασικές δραστηριότητες: • Καταγραφή Απαιτήσεων Ενδιαφερόμενων Μερών, Λογισμικού και Συστήματος (Requirements)

Οι μηχανικοί λογισμικού έρχονται σε επικοινωνία με τους πελάτες. Οι πελάτες μπορεί να είναι ιδιωτικές επιχειρήσεις και εταιρείες, δημόσιοι φορείς και πάσης φύσεως οργανισμοί. Τις ομάδες αυτές τις ονομάζουμε και stakeholders ή ενδιαφερόμενα μέρη. Έτσι τα ενδιαφερόμενα μέρη περιγράφουν στους μηχανικούς το λογισμικό. Η περιγραφή μπορεί να περιλαμβάνει λειτουργικότητα, επιχειρισιακές διαδικασίες, αλληλεπιδράσεις με εξωτερικά περιβάλλοντα (π.χ. άλλα λογισμικά ή εταιρείες), αισθητικές προδιαγραφές και ότι άλλο κρίνει ο πελάτης ότι θέλει να ξέρει ο μηχανικός. Οι προδιαγραφές αυτές με όρους Τεχνολογίας Λογισμικού ονομάζονται Requirements ή Απαιτήσεις. Επίσης κατά την δραστηριότητα αυτή καταγράφονται και οι τεχνικές απαιτήσεις του λογισμικού και του συστήματος γενικότερα. Η καταγραφή αυτή γίνεται κυρίως από τους μηχανικούς και προκύπτει από τις απαιτήσεις των ενδιαφερόμενων μερών. Στο τέλος της καταγραφής όλων των απαιτήσεων οι μηχανικοί έχουν στα χέρια τους 3 έγγραφα: – Απαιτήσεις χρηστών (User Requirements) – Απαιτήσεις Λογισμικού (Software Requirements) – Απαιτήσεις Συστήματος (System Requiremenrs) Με όρους αγοράς, η δραστηριότητα αυτή είναι κατά μία έννοια η ”παραγγελία”. • Τυποποίηση Απαιτήσεων και Αφαιρετικός Σχεδιασμός Λογισμικού (De- sign)

Οι μηχανικοί λογισμικού κωδικοποιούν τις απαιτήσεις σε διαγράμματα σχέσεων μεταξύ οντοτήτων και ροής εργασιών. Επίσης το στάδιο αυτό περιλαμβάνει συνολική σχεδίαση λογισμικού με την σύνδεση των τριών εγγράφων. Η δραστηριότητα αυτή αντιστοιχεί παραδείγματος χάρη στα σχέδια (blueprints) κατασκευής ενός αυτοκινήτου. Κεφάλαιο 2. Υπόβαθρο 28

• Υλοποίηση Λογισμικού (Construction)

Ο σχεδιασμός υλοποιείται. Συγγράφεται κώδικας που πραγματοποιεί όλες τις απαιτήσεις. Στο στάδιο αυτό κυριαρχούν οι προγραμματιστές. Είναι ο πυρήνας της ανάπτυξης λογισμικού. Μέσω της υλοποίησης γίνεται η ιδέα πράξη. Στο στάδιο αυτό ενδέχεται να αξιοποιούνται προσωρινά περιβάλλοντα στα οποία θα εκτελείται το λογισμικό. Αυτό διότι δεν ενδιαφέρει ακόμα η πλήρης λειτουργία του συστήματος που σχεδιάζεται • Συνολική Δοκιμή Λογισμικού (Testing)

Ο κώδικας δοκιμάζεται. Εκτελούνται τεστ που προσομοιώνουν την λειτουργία του λογισμικού και ελέγχεται – Αν προκύπτουν προβλήματα λογισμικού λόγω συντακτικών ή λογικών λαθών κατά την συγγραφή του κώδικα. – Αν όλα εκτελούνται όπως έχουν συμφωνηθεί στις απαιτήσεις. • Συνολική Αποσφαλμάτωση Λογισμικού (Debugging)

Η εμπειρία δείχνει ότι πάντα προκύπτουν προβλήματα κατά την δραστηριότητα των δοκιμών. Έτσι αναγκαστικά υπάρχει και οι δραστηριότητα της αποσφαλμάτωσης. Κατά την αποσφαλμάτωση οι μηχανικού λογισμικού εντοπίζουν και διορθώνουν τα λάθη που προέκυψαν από τις δοκιμές. • Ανάπτυξη Λογισμικού (Deployment)

Αφού το λογισμικό έχει υλοποιηθεί και λειτουργεί σωστά και όπως συμφωνήθηκε, οι μηχανικοί αναλαμβάνουν να το εγκαταστήσουν. Έτσι αφαιρούνται τα προσωρινά συστήματα και αντικαθιστώνται από πραγματικά. Δηλαδή από εξυπηρετητές (servers), βάσεις δεδομένων (databases) και δικτυακές συνδέσεις (network con- nections). Η δραστηριότητα αυτή ταυτίζεται με την ”διάθεση του λογισμικού”, στους πελάτες και τους χρήστες τους. Για παράδειγμα όλες οι ιστοσελίδες που βλέπουμε στο διαδίκτυο, όλα τα λειτουργικά συστήματα που χρησιμοποιούμε σε όλες τις συσκευές μας και όλα τα προγράμματα που εκτελούνται σε αυτά, είναι αποτέλεσμα του Deployment. Τέλος κατά το Deployment καταστρώνονται και τα σχέδια συντήρησης και ανάπτυξης του λογισμικού. • Συντήρηση Λογισμικού (Maintenance)

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

Η παραπάνω δραστηριότητες και η ακολουθία εκτέλεσής τους φαίνεται στην εικόνα 2.18. Πίσω από κάθε δραστηριότητα κρύβεται ένα σύνολο διαδικασιών οι οποίες οδηγούν στην πραγματοποίησή της και ακολουθούνται από ομάδες λογισμικού. Οι διαδικασίες εντός Κεφάλαιο 2. Υπόβαθρο 29

Εικόνα 2.18: Οι βασικές δραστηριότητες ανάπτυξης λογισμικού

της δραστηριότητας αλλά και η ακολουθία των ίδιων των δραστηριοτήτων ποικίλουν από λογισμικό σε λογισμικό. Έτσι σήμερα στην βιομηχανία εμφανίζονται διάφορα μοντέλα ανάπτυξης λογισμικού όπως τα Waterfall, Spiral, Prototyping (εικόνα 2.19), RUP, Agile και DevOps. Εσωτερικά των μοντέλων τώρα έχουν αναπτυχθεί μεθοδολογίες ανάπτυξης λογισμικού, οι οποίες αφορούν τις ενέργειες της κάθε δραστηριότητας. Τέτοιες μεθοδολογίες είναι η Ανάπτυξη Λογισμικού Οδηγούμενη από Δοκιμές (Test Driven Devel- opment) και η Ανάπτυξη Λογισμικού Οδηγούμενη από Συμπεριφορές (Behavior Driven De- velopment). Οι μεθοδολογίες αυτές εντάσσονται, γενικώς, στο Agile μοντέλο ανάπτυξης λογισμικού. Κατά το Agile μοντέλο, η Διαδικασία Ανάπτυξης Λογισμικού είναι ευέλικτη. Οι βασικές αρχές του Agile μοντέλου είναι η συνεχής συνεργασία μεταξύ πελατών- μηχανικών, και η συνεχής διαμόρφωση των απαιτήσεων και του λογισμικού ως αποτέλεσμα αυτής της συνεργασίας. Έτσι κατά την διαδικασία Agile δεν ακολουθούμε πιστά και με την σειρά τις 7 προαναφερθέντες δραστηριότητες, αλλά προσαρμοζόμαστε στις συνθήκες. Όπως θα δούμε στην συνέχεια το BDD ταιριάζει περισσότερο από το TDD στο Agile μοντέλο.

2.2.1.1 Test Driven Development

Η ιδέα των πρώιμων δοκιμών κατά την ανάπτυξη λογισμικού, εμφανίστηκε από τον Kent Beck στην μεθοδολογία του eXtreme Programming (XP) το 1999 [6][5]. Ο ίδιος ο Kent Beck, στην συνέχεια, καθιέρωσε την μεθοδολογία ανάπτυξης λογισμικού οδηγούμενη από δοκιμές. Δηλαδή καθιέρωσε το επονομαζόμενο Test Driven Development ή απλά TDD [27]. Στο Test Driven Development το λογισμικό ξεκινάει από το τεστ. Δηλαδή από την 4η δραστηριότητα της εικόνας 2.18. Το τεστ αυτό αναφέρεται και ως unit test. Διαφέρει όμως από το unit test που συγγράφεται αφού έχει υλοποιηθεί το λογισμικό. Κατά την μεθοδολογία TDD, ο Kent Beck περιγράφει την παρακάτω ακολουθία βημάτων ανάπτυξης λογισμικού [2]: 1. Δημιουργία ενός νέου τεστ T

Κατά το στάδιο αυτό δημιουργείται ένα νέο τεστ. Το τεστ προκύπτει από τις Κεφάλαιο 2. Υπόβαθρο 30

Εικόνα 2.19: Διαδεδομένα μοντέλα ανάπτυξης λογισμικού [25]

απαιτήσεις και τις συνθήκες εξαιρέσεων του συστήματος. Αυτές με την σειρά τους προκύπτουν από τα σενάρια χρήσης του συστήματος. 2. Εκτέλεση όλων τεστ και διαπίστωση αν αποτυγχάνει το T

Το στάδιο αυτό έχει σκοπό να επιβεβαιώσει την χρησιμότητα του T . Αν το T περνάει (pass), τότε δεν έχει χρησιμότητα. Έχει νόημα να πάμε στο επόμενο στάδιο, μόνο το T αποτυγχάνει (fail). 3. Συγγραφή του κώδικα

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

Τρέχουμε για άλλη μία φορά τα τεστ ώστε να δούμε αν το T περνάει. Επίσης, Κεφάλαιο 2. Υπόβαθρο 31

σε αυτό το στάδιο εξετάζουμε αν η εισαγωγή του κώδικα δεν προκάλεσε προβλήματα σε άλλα τεστ και στην λειτουργικότητα του λογισμικού γενικότερα. Μέχρι το λογισμικό να είναι λειτουργικό επιστρέφουμε στο βήμα (3) και διορθώνουμε τον κώδικα. 5. Διόρθωση του συνολικού κώδικα

Είπαμε στο βήμα (3) ότι δεν μας ενδιαφέρει η ποιότητα του κώδικα. Σε αυτό το στάδιο όλα τα τεστ (και το T ), έχουν περάσει. Πλέον μπορούμε να κάνουμε τις απαραίτητες αλλαγές, ώστε ο νέος κώδικας να ενσωματωθεί ποιοτικά στον υπάρχων συνολικό. 6. Επανάληψη διαδικασίας από την αρχή Η παραπάνω διαδικασία αναπαρίσταται σχηματικά στην εικόνα 2.20

Εικόνα 2.20: Διάγραμμα εξέλιξης διαδικασίας συγγραφής λογισμικού κατά TDD2

2.2.1.2 Acceptance TDD και Behavior Driven Development

Η διαδικασία που περιγράψαμε πιο πάνω, προϋποθέτει ότι ο μηχανικός λογισμικού γνωρίζει καλά τα σενάρια χρήσης του συστήματος. Έτσι επικεντρώνεται στο να δοκιμάζει πώς το εκάστοτε σενάριο θα ενταχθεί στο σύστημα. Μία άλλη προσέγγιση είναι το Ac- ceptance TDD ή ATDD. Σήμερα η δημιουργία λογισμικού αφορά εταιρείες, οργανώσεις, δημόσιους φορείς. Αυτές τις ομάδες τις ονομάζουμε ενδιαφερόμενα μέρη (stakeholders). Επιπλέον η βιομηχανία λογισμικού έχει εξελιχθεί αρκετά, ώστε τα ενδιαφερόμενα μέρη

2http://agiledata.org/essays/tdd.html Κεφάλαιο 2. Υπόβαθρο 32

να διαθέτουν σχετικό τεχνικό προσωπικό. Το προσωπικό αυτό έχει την τεχνική κατάρτιση να εκπροσωπήσει την εταιρεία στην διαδικασία συγγραφής λογισμικού, και άρα και στην διαδικασία δοκιμών. Όταν στην διαδικασία δοκιμών συμμετέχουν έμμεσα ή άμεσα και εκπρόσωποι εταιρειών, τότε η διαδικασία ονομάζεται ATDD. Παραδείγματα acceptance test βλέπουμε στους πίνακες 2.2 και 2.3 [1].

Εικόνα 2.21: Ο κύκλος ζωής της μεθοδολογίας TDD3

Εικόνα 2.22: Διαδικασία συγγραφής acceptance test

Η εξέλιξη του ATDD είναι το Behavior Driven Development ή BDD. Το BDD ονομάστηκε έτσι από τον Dan North το 2003. Βασίζεται στην λογική του TDD με την διαφορά ότι τα τεστ κατά BDD ονομάζονται Ιστορίες Χρηστών ή User Stories. Δηλαδή περιγραφές ή σενάρια χρήσης του λογισμικού και του συστήματος γενικότερα. Οι περιγραφές

3https://en.wikipedia.org/wiki/Test-driven_development Κεφάλαιο 2. Υπόβαθρο 33

Description Checking accounts have an overdraft limit of $500. As long as there are sufficient funds (e.g. -$500 or greater) within a check- ing account after a withdrawal has been made the withdrawal will be allowed. Setup 1. Create account 12345 with an initial balance of $50 2. Create account 67890 with an initial balance of $0

Instructions 1. Withdraw $200 from account #12345 2. Withdraw $350 from account #67890 3. Deposit $100 into account #12345 4. Withdraw $200 from account #67890 5. Withdraw $150 from account #67890 6. Withdraw $200 from account #12345 7. Deposit $50 into account #67890 8. Withdraw $100 from account #67890

Expected Results Account #12345: • Ending balance = -$250 • $200 Withdrawal transaction posted against it • $100 Deposit transaction posted against it • $200 Withdrawal transaction posted against it Account #67890: • Ending balance = -$500 • $350 Withdrawal transaction posted against it • $150 Withdrawal transaction posted against it • $50 Deposit transaction posted against it Errors logged: • Insufficient funds in Account #67890 (balance -$350) for $200 Withdrawal • Insufficient funds in Account #67890 (balance -$450) for $100 Withdrawal

Πίνακας 2.2: Acceptance test με στόχο την επικύρωση ενός επιχειρησιακού κανόνα Κεφάλαιο 2. Υπόβαθρο 34

Description The customer search screen allows user to perform standard wildcard searches on first and last name. Setup 1. Remove all customer records from the database. 2. Add the following customers: • John Smith • James Doe • Robin Saunders • Jim Saunders • Sally Smith • Scott Davidson • Beverley Williams • Bob Roberts • Rob Williams • Robert Smithers • Bobby Snookerby • Sandy Davington • Janice Sinters

Instructions • Display the Customer search screen. • In the First Name entry field, enter ” • In the Last Name entry field, enter ”S*” • Press the search button.

Expected Results The following names should be displayed in the search result box: • Robin Saunders • Robert Smithers • Bobby Snookerby

Πίνακας 2.3: Acceptance test με στόχο την επικύρωση μέρους διεπαφής χρήστη Κεφάλαιο 2. Υπόβαθρο 35

αυτές προκύπτουν από την συνεννόηση μεταξύ των stakeholders και των μηχανικών λογισμικού. Χαρακτηριστικό στοιχείο των User Stories και του BDD γενικότερα είναι η απλή, αφηγηματική γλώσσα. Το Νοέμβριο του 2007 ο Dan North έδωσε σε παρουσίαση του τον εξής ορισμό για το BDD: ”BDD is a second-generation, outside–in, pull-based, multiple-stakeholder, multiple-scale, high-automation, agile methodology. It describes a cycle of interactions with well-defined outputs, resulting in the delivery of working, tested software that matters.” [10] Από τον ορισμό αυτό παρατηρούμε μεταξύ άλλων ότι και το BDD ξεκινάει από το τεστ. Η μέθοδος αυτή ονομάζεται outside-in. Πολλές φορές στην βιβλιογραφία το BDD παρουσιάζεται ώς εναλλακτική ή ακόμα και ίδιο με το ATDD. Στην πραγματικότητα το BDD διαφοροποιείται και από το ATDD (πέραν του TDD) έως ένα βαθμό. Είπαμε ότι κατά BDD τα τεστ ονομάζονται ιστορίες χρηστών και περιγράφονται σε απλή, αφηγηματική γλώσσα. Ας συγκρίνουμε τα παρακάτω παραδείγματα: Παράδειγμα 2.7: ATDD Acceptance Test Verify that customer authentication works Παράδειγμα 2.6: Verify that the customer is BDD User Story limited to 3 transactions an As a customer ATM session I want to withdraw cash Verify that sufficient balance from an ATM, is in place to support so that I dont have to wait the transaction in line at the bank Verify that the overall transaction workflow takes no longer than 5 minutes Verify that the transaction is immediately viewable in the customers online access

Το παράδειγμα 2.6, είναι ένα σενάριο χρήσης κατά BDD, το οποίο περιγράφει μία επιχειρησιακή διαδικασία. Η διαδικασία αυτή δεν είναι άλλη από την ανάληψη χρημάτων από ένα ATM μιας τράπεζας. Στο παράδειγμα 2.7 βλέπουμε ακριβώς την ίδια επιχειρησιακή διαδικασία διατυπωμένη από την οπτική γωνία του ATDD. Παρατηρούμε ότι και τα δύο κείμενα είναι κατανοητά. Αυτό συμβαίνει διότι είναι αποτέλεσμα συννενόησης των εκπροσώπων με τους μηχανικούς λογισμικού. Η διαφορά τους όμως είναι εμφανής. Το acceptance Test περιέχει τεχνικές λεπτομέρεις που αφορούν την διαδικασία ανάληψης (όπως τα όρια στο πλήθος και στο χρόνο των συναλλαγών). Το BDD User Story δεν επικεντρώνεται σε τέτοιες τεχνικές λεπτομέρεις, αλλά στην ιστορία αυτή καθαυτή. Βασικό του χαρακτηριστικό είναι ότι απαντάει στο γιατί να υπάρχει η επιχειρησιακή διαδικασία ”ανάληψη από ATM” και όχι στο πώς αυτή υλοποιείται. Αυτό όμως δεν σημαίνει ότι αυτές οι τεχνικές λεπτομέρειες δεν μας ενδιαφέρουν. Το λογισμικό κάποια στιγμή θα υλοποιηθεί (ας θυμηθούμε την εικόνα 2.18). Οι τεχνικές λεπτομέρειες θα εμφανιστούν σε μετέπειτα στάδιο της ανάπτυξης του λογισμικού και αφορούν περισσότερο τους testers και τους προγραμματιστές. Στην πραγματικότητα τα σημερινά User Stories περιγράφουν πλήρως και το επιχειρησιακό domain του πελάτη. Επιλέχθηκε όμως να γίνει η παραπάνω παρουσίαση ώστε να φανεί καθαρά η διαφορά μεταξύ αφήγησης και απλής παράθεσης τεχνικών πληροφοριών. Έτσι κατά BDD διακρίνουμε τα εξής βήματα ανάπτυξης λογισμικού: Κεφάλαιο 2. Υπόβαθρο 36

1. Συγγραφή του User Story Οι πελάτες, οι testers και οι προγραμματιστές συμφωνούν στο τι θα κάνει το λογισμικό και γιατί. Αποτέλεσμα αυτής της διαδικασίας είναι το User Story. Το User Story περιγράφει ένα νέο χαρακτηριστικό του λογισμικού. 2. Δοκιμή του User Story από τους testers Η δοκιμή ακολουθεί πιστά το πρότυπο TDD του Kent Beck, το οποίο περιγράψαμε πιο πάνω. Κατά την δοκιμή ενδεχομένως συνεννοούνται με τους προγραμματιστές για τις διάφορες τεχνικές λεπτομέρειες. Σε αυτό το στάδιο ενδεχομένως ακολουθούν μεταξύ τους μία σύντομη διαδικασία συγγραφής Acceptance Test, το οποίο ουσιαστικά θα είναι η αποκωδικοποίηση των τεχνικών λεπτομερειών του User Story. 3. Επικοινωνία με τους πελάτες για την εξέλιξη της διαδικασίας Αν κατά το βήμα τρία προκύψουν επιπλοκές με τα άλλα υπάρχοντα User Stories, τότε πρέπει να γίνει ξανά συζήτηση με τους πελάτες. Στο σημείο αυτό οι μηχανικοί εξηγούν στους πελάτες τα διάφορα προβλήματα που προέκυψαν με τα υπόλοιπα User Sto- ries. Να επισημάνουμε εδώ ότι δεν τους μεταφέρουν τα τεχνικά προβλήματα που προέκυψαν. Αυτά αφορούν τους μηχανικούς λογισμικού. Τα μόνα προβλήματα τα οποία είναι σχετικά με αυτή την συζήτηση είναι αυτά που αφορούν την λειτουργία του λογισμικού όπως αυτή περιγράφηκε στο βήμα (1). Η συζήτηση αυτή δεν βοηθάει μόνο τους πελάτες αλλά και τους μηχανικούς λογισμικού. 4. Επανάληψη από το βήμα (1) Το βήμα (1) ξεκινάει με την ”διόρθωση του User Story”

Αποτέλεσμα της διαδικασίας BDD είναι να έχουμε μία συνεχόμενη συμμετοχή όλων των πλευρών στην συγγραφή του λογισμικού. Μάλιστα λόγω των User Stories η συμμετοχή των εκπροσώπων του εκάστοτε πελάτη διευρύνεται. Πλέον στην συζήτηση μπορούν να συμμετάσχουν όλων των ειδών οι εκπρόσωποι της εταιρείας, του φορέα ή του οργανισμού. Αυτό γιατί το User Story είναι κάτι που όχι μόνο καταλαβαίνουν όλοι, αλλά μπορούν και να βοηθούν στην συγγραφή του. Το User Story μπορεί να περιέχει και τεχνικά χαρακτηριστικά που αφορούν τον χώρο της εταιρείας. Στην βιβλιογραφία η μέθοδος αυτή αναφέρεται και ως Domain Driven Design4. Δηλαδή σχεδιασμός με βάση τα τεχνικά χαρακτηριστικά του χώρου, γύρω από τον οποίο αναπτύσσεται το λογισμικό.

Τώρα όσο αφορά τις διαφορές των 3 μεθόδων, στην εικόνα 2.23 μπορούμε να δούμε την συνεισφορά των διαφόρων ομάδων κατά BDD, ATDD και TDD. Η συνεισφορά αφορά την συγγραφή του τεστ. Δηλαδή του απλού τεστ κατά TDD, του Acceptance Test κατά ATDD και του User Story κατά BDD. Βλέπουμε λοιπόν ότι στην δημιουργία του User Story, η εμπλοκή των ενδιαφερόμενων μερών είναι πολύ μεγαλύτερη από τις άλλες δύο περιπτώσεις. Έτσι αιτιολογείται ο τίτλος Behavior Driven Development. Δηλαδή η ανάπτυξη του λογισμικού, οδηγείται (driven) από το User Story. Άρα από την καθοριστική συνεισφορά των ενδιαφερόμενων μερών. Στο ATDD οι συνεισφορά είναι πιο ισορροπημένη. Οι εκπρόσωποι των πελατών είναι κυρίως τεχνικά στελέχη και άρα εκπροσωπούν έως ένα βαθμό τους πρώτους. Τέλος στο TDD η μόνη συνεισφορά του πελάτη είναι μία αρχική συζήτηση, στην οποία περιγράφει προφορικά τις απαιτήσεις λογισμικού. Ως τελικό σχόλιο αναφέρουμε ότι το BDD δεν εμφανίστηκε λόγω κάποιας επιστημονικής προσεγγίσεως που αναιρεί το ATDD. Περαιτέρω τόσο το TDD όσο και το ATDD συνεχίζουν να χρησιμοποιούνται από ομάδες λογισμικού. Το ATDD αποτελεί την γέφυρα ανάμεσα στις μεθοδολογίες BDD και TDD. Αυτό μπορούμε να το καταλάβουμε αν εξετάσουμε πάλι την εικόνα 2.23. Αν στο ATDD Test Discussion μετακινήσουμε το όριο μεταξύ

4https://en.wikipedia.org/wiki/Domain-driven_design Κεφάλαιο 2. Υπόβαθρο 37

Εικόνα 2.23: Συμμετοχή διαφόρων ομάδων στην συγγραφή δοκιμών κατά BDD, ATDD, TDD

Business Stakeholders και Testers προς τα αριστερά, τότε έχουμε το BDD. Αντίθετα αν το μετακινήσουμε προς τα δεξία τότε έχουμε το TDD. Έτσι οι διαφορές των τριών μεθοδολογιών είναι διακριτές, αλλά όχι σταθερές. Επισημαίνουμε έτσι ότι δεν υπάρχει ”σωστή” μέθοδος, αλλά υπάρχουν ανάγκες τις αγοράς και τεχνολογικές εξελίξεις.

2.2.2 Gherkin

Η γλώσσα Gherkin[8] είναι μία γλώσσα συγγραφής User Stories. Η Gherkin αποτελεί μέρος του BDD εργαλείου Cucumber, το οποίο σύντομα εξηγείται στο παράρτημα A. Η Gherkin ορίζει την οργάνωση των User Stories σε feature files ή aρχεία xαρακτηριστικών. Επίσης ορίζει ένα συντακτικό συγγραφής feature files. Το συντακτικό των feature files αποτελείται από τα εξής 3 δομικά στοιχεία: • Τα χαρακτηριστικά (features) • Τα σενάρια (scenarios) • Τα βήματα (steps) Κάθε χαρακτηριστικό αποτελείται από ένα ή περισσότερα σενάρια. Επιπλέον κάθε σενάριο αποτελείται από μία σειρά βημάτων. Η κλασσική δομή ενός αρχείου χαρακτηριστικών φαίνεται στην εικόνα 2.24. Βλέπουμε ότι οι λέξεις κλειδιά (keywords) βρίσκονται στην αρχή των προτάσεων. Κάτω από τις λέξεις κλειδιά feature: και scenario: υπάρχουν οι περιγραφές τους. Αυτές είναι προαιρετικές και υπάρχουν μόνο για να βοηθούν την ομάδα ανάπτυξης λογισμικού στην κατανόηση, την συγγραφή και την οργάνωση των feature files. Η δομή του feature file είναι τέτοια ώστε να συμβάλλει στην συγγραφή του User Story. Τα features αντιστοιχούν στα ”χαρακτηριστικά του λογισμικού ή συστήματος” το οποίο σχεδιάζουμε. Τα scenarios αφορούν τα διάφορα σενάρια χρήσης του λογισμικού. Τα Κεφάλαιο 2. Υπόβαθρο 38

Εικόνα 2.24: Ένα Cucumber feature file steps είναι μια ακολουθία ενεργειών που περιγράφουν το εκάστοτε σενάριο χρήσης.

Το ισχυρό χαρακτηριστικό της γλώσσας Gherkin και του Cucumber γενικότερα είναι ο τρόπος περιγραφής των βημάτων των σεναρίων. Συγκεκριμένα, το ισχυρο χαρακτηριστικό είναι η προδιαγραφή να περιγράφονται τα steps με την λογική Given - When - Then και την ενδεχόμενη προσθήκη των But και And. Η λογική αυτή μοιάζει με το if - and - then του προγραμματισμού. Δηλαδή το μοντέλο αιτία-αποτέλεσμα [29]. Στο σημείο αυτό πρέπει να σταθούμε. Το if - and - then αποτελεί βασικό δομικό στοιχείο του προγραμματισμού ως φιλοσοφία. Η ίδια η σχεδίαση των λογικών κυκλωμάτων βασίζεται στην λογική αν-τότε. Έτσι παραδείγματος χάρη μπορούμε πολύ εύκολα να περιγράψουμε με ένα feature file την λογική πύλη AND (εικόνα 2.25). Η λογική αν-τότε διέπει συνολικά την Επιστήμη των Υπολογιστών. Στην θεωρία των υπολογισμών π.χ., η λογική αυτή περιγράφεται από τις μηχανές καταστάσεων. Έτσι το Given - When - Then αντιστοιχεί και στην λογική: Δεδομένου (Given) ότι είμαι στην κατάσταση Α, Όταν/Και (When/And) ισχύουν κάποιες συνθήκες Χ, Τότε (Then) μεταβαίνω στην κατάσταση Β. Με βάση αυτή την διαπίστωση, η λογική Given - When - Then ενισχύει την επικοινωνία μεταξύ μηχανικών λογισμικού και ενδιαφερόμενων μερών. Αν και αυτές οι δύο ομάδες έχουν διαφορετικές οπτικές γωνείες, η Gherkin καθοδηγεί τον τρόπο σκέψης τους. Αυτή η ιδιότητα είναι δομικής σημασίας για την γεφύρωση του χάσματος. Όχι απλώς τα User Stories είναι απλά και κατανοητά, αλλά ακολουθούν ταυτόχρονα την λογική ενός αλγόριθμου. Επιπρόσθετα χάρη στα feature files και την δομή τους, τα User Stories μπορούν πολύ εύκολα να γραφτούν γύρω από ένα ubiquitous language. Δηλαδή γλώσσα σχετική με την δραστηριότητα του φορέα, της εταιρείας ή του οργανισμού (domain driven design). Εφόσον οι περιορισμοί των feature files είναι μόνο η απλή δομή και το λογικό συντακτικό των steps, υπάρχει μεγάλο περιθώριο ελευθερίας για την περιγραφή του User Story. Κεφάλαιο 2. Υπόβαθρο 39

Εικόνα 2.25: Η λογική πύλη AND κατά Cucumber. Σημειώνεται ότι το And μπορεί κάλλιστα να αντικατασταθεί από το When

Το περιθώριο αυτό διευρύνεται και από την δυνατότητα πρόσθεσης περιγραφής (descrip- tion) στο εκάστοτε feature και scenario. Έτσι ο πελάτης μπορεί να δώσει στοχευμένα και συγκεκριμένα παραδείγματα των επιχειρησιακών διαδικασιών του χώρου του. Ταυτόχρονα τα feature files αποτελούν ένα κοινό σημείο αναφοράς για την ομάδα ανάπτυξης λογισμικού. Όλες οι απαιτήσεις είναι καταγεγραμμένες και ξεκάθαρες. Επιπρόσθετα τα feature files παρακολουθούν τις εξελίξης του λογισμικού και άρα ενημερώνονται συνεχώς. Έτσι οι απαιτήσεις του συστήματος παραμένουν επίκαιρες. Δηλαδή τα feature files μπορούν να παίξουν και τον ρόλο του documentation του συστήματος. Documentation μάλιστα που μπορούν να διαβάσουν όλοι οι συμμετέχοντες στην διαδικασία και που συνεχώς ενημερώνεται (living documentation). Στο βιβλίο The Cucumber Book [32] το κοινό αυτό σημείο συνάντησης αναφέρεται ως source of truth. Επισημαίνεται τέλος ότι στην σουίτα εργαλείων που παρέχει το Cucumber, συμπεριλαμβάνεται και ο Gherkin Parser5. Ο Gherkin Parser δέχεται ως είσοδο

5https://github.com/cucumber/gherkin Κεφάλαιο 2. Υπόβαθρο 40 feature files και δίνει ως έξοδο ένα μοντέλο χαρακτηριστικών που αποκαλείται Abstract Syntax Tree (AST). Η δομή του AST φαίνεται στην εικόνα 2.26. Την λειτουργία αυτή του Gherkin Parser θα την αξιοποιήσουμε στο σύστημά μας.

Εικόνα 2.26: Το Abstract Syntax Tree του Gherkin Parser Κεφάλαιο 2. Υπόβαθρο 41

2.3 Natural Language Processing

Το Natural Language Processing ή απλά NLP, είναι η επιστήμη που ασχολείται με τις αλληλεπιδράσεις μεταξύ των υπολογιστών και των φυσικών γλωσσών των ανθρώπων [16]. Το NLP έγινε γνωστό με το Turing Test6 του Alan Turing. Κατά το Turing Test ένας άνθρωπος, ο δοκιμαστής, προσπαθεί να διακρίνει μία μηχανή από έναν άλλον άνθρωπο. Για να το πετύχει αυτό, του δίνεται η δυνατότητα να θέτει γραπτά ερωτήματα και στους δυο (και μόνο). Ο άνθρωπος και η μηχανή απαντάνε και ο δοκιμαστής, ανάλογα με τις απαντήσεις, αποφασίζει ποιος από τους δύο έδωσε ποια απάντηση. Στόχος του τεστ είναι προφανώς να πείσει η μηχανή τον δοκιμαστή ότι είναι άνθρωπος. Για να τον πείσει, καταστρατηγεί μεθόδους NLP τόσο κατά την ανάγνωση των ερωτημάτων όσο και κατά την διαμόρφωση των απαντήσεων. Η εξέλιξη του NLP στη δεκαετία του 80 ήταν ραγδαία για τρείς λόγους. Ο πρώτος είναι η συνεχόμενη αύξηση της υπολογιστικής ισχύος, ο δεύτερος οι συνεχώς βελτιωμένοι αλγόριθμοι υπολογισμών και ο τρίτος η εισαγωγή και η εξέλιξη της μηχανικής μάθησης. Ταυτόχρονα το μικρό κόστος διαχείρισης ψηφιακού κειμένου, σε αντίθεση με το χειρόγραφο, οδήγησε στο φαινόμενο της λεγόμενης ”μηχανογράφησης”. Έτσι επιχειρήσεις, οργανισμοί και κράτη συνολικά, ανέλαβαν την ψηφιοποίηση πάσης φύσεως εγγράφων σχετικών με την λειτουργία τους. Φυσικά στην εξέλιξη του NLP συνέβαλε και η ραγδαία εξέλιξη του Παγκόσμιου Ιστού. Χαρακτηριστικό παράδειγμα είναι οι μηχανές αναζήτησης. Οι τελευταίες αξιοποιούν κατά το δυνατόν καλύτερα την επεξεργασία φυσικής γλώσσας για την στοχευμένη εύρεση πληροφορίας. Συμπερασματικά η γενικότερη τεχνολογική έκρηξη του 20ου αιώνα είναι άμεσα συνδεδεμένη με την εξέλιξη του NLP. Παρά τους πολλούς κλάδους του NLP, το πεδίο εφαρμογής της διπλωματικής είναι συγκεκριμένο. Την περίπτωσή μας αφορά η εξαγωγή τεχνικής πληροφορίας από κείμενο γραμμένο σε γλώσσα Gherkin. Μάλιστα το περιεχόμενο του κειμένου αφορά την περιγραφή ενός Web API. Έτσι αυτά που αναμένονται να ”εμφανιστούν” εντός του κειμένου, οριοθετούνται από το συντακτικό της Gherkin και τα τεχνικά χαρακτηριστικά των Web APIs. Πρέπει να αναφέρουμε ακόμη ότι πρώτος στόχος της διπλωματικής είναι η απεικόνιση απαιτήσεων RESTful Web APIs σε Gherkin. Άρα, και σχεδιαστικά, μπορούμε να ”προβλέψουμε” το πώς ο μηχανικός θα συντάσσει τις απαιτήσεις σε Gherkin. Με βάση αυτή την οριοθέτηση, τα εργαλεία που θα δανειστούμε από το NLP είναι το Tokenization, το POS Tagging, το Text chunking και το Relation Extraction. Επίσης αξιοποιούμε τα Regular Expressions αλλά και λίστες λέξεων ή φράσεων. Τα εργαλεία αυτά επεξηγούμε σύντομα παρακάτω. Θα πρέπει εδώ να επισημάνουμε ότι οι απαιτήσεις των Web APIs σε Gherkin θα γράφονται στην αγγλική γλώσσα.

2.3.1 Information Extraction

Τα πρώτα τέσσερα εργαλεία, δηλαδή τα Tokenization, POS Tagging, Text chunking, Relation Extraction, συνθέτουν την διαδικασία Information Extraction (ΙΕ). Κατά την διαδικασία αυτή το κείμενο περνάει από διάφορα στάδια επεξεργασίας. Κάθε στάδιο εμπλουτίζει περισσότερο το σύνολο των πληροφοριών που σχετίζονται με το περιεχόμενό του. Το κάθε στάδιο αναλύεται παρακάτω.

6https://en.wikipedia.org/wiki/Turing_test Κεφάλαιο 2. Υπόβαθρο 42

2.3.1.1 Tokenization

Κατά το Tokenization, οι προτάσεις του κειμένου διαχωρίζονται σε tokens. Δηλαδή στις μικρότερες δυνατές εννοιολογικές μονάδες. Έτσι για παράδειγμα στην πρόταση I ate breakfast

τα tokens είναι τα ”I”, ”ate” και ”breakfast”. Αντίστοιχα στην πρόταση When I request an order by it's id

τα tags είναι τα ”When”, ”I”, ”request”, ”an”, ”order”, ”by”, ”it”, ”’s”, ”id”.

2.3.1.2 POS Tagging

Το Part of Speech Tagging ή απλά POS Tagging είναι μία μεθοδολογία ”ετικετοποίησης” λέξεων με βάση τα συντακτικά και γραμματικά τους χαρακτηριστικά. Δεδομένου ότι η γλώσσα που μας αφορά είναι η αγγλική, αναφερόμαστε πάντα στο συντακτικό και την γραμματική της αγγλικής γλώσσας. Γνωστά μέρη του λόγου της αγγλικής γλώσσας είναι τα noun, verb, adjective, adverb, pronoun, preposition, conjunction, interjection, numeral, article/determiner. Από αυτά τα μέρη του λόγου προκύπτουν οι λεγόμενες ετικέτες (tags). Επειδή μερικές λέξεις δεν έχουν ξεκάθαρη ετικετοποίηση, προκύπτουν διαφορετικά σετ ετικετών. Ενδεικτικά παραθέτουμε το γνωστό Penn Treebank στην εικόνα 2.30. Είσοδος του POS Tagging είναι ένα tokenized κείμενο. Αποτέλεσμα εφαρμογής του POS Tagging σε μία πρόταση είναι ένας πίνακας, ο οποίος στην μία του στήλη περιέχει τις λέξεις της πρότασης και στην άλλη τα αντίστοιχα tag τους.

2.3.1.3 Text Chunking

Το POS Tagging βρίσκει τα μέρη του λόγου σε μία πρόταση. Μία άλλη ενδιαφέρουσα πληροφορία είναι οι ονοματικές προτάσεις (κύριες και δευτερεύουσες). Ο εντοπισμός αυτών μπορεί να γίνει με την μεθοδολογία Text Chunking. Το text chunking λαμβάνει ως είσοδο ετικετοποιημένο κείμενο κατά POS Tagging και έχει ως έξοδο ομάδες φράσεων. Οι φράσεις σηματοδοτούνται με την ακολουθία χαρακτήρων ’NP’ (Noun Phrase). Στην εικόνα 2.27 φαίνεται το αποτέλεσμα εφαρμογής POS Tagging και Chunking σε μία πρόταση.

Εικόνα 2.27: Αποτέλεσμα εφαρμογής POS Tagging και Text Chunking σε μία πρόταση Κεφάλαιο 2. Υπόβαθρο 43

2.3.1.4 Named Entity Recognition

Tο Named Entity Recognition αφορά τον εντοπισμό ονοματικών φράσεων και ουσιαστικών και την ταξινόμησή τους σε κατηγορίες. Τέτοιες κατηγορίες μπορεί να είναι οργανισμοί, περιοχές, πρόσωπα, μονάδες μέτρησης, νομισματικές μονάδες κ.λ.π.. Ο εντοπισμός και η ταξινόμηση των entities μπορεί να γίνεται με βάση κάποιες λίστες εκφράσεων ή λέξεων. Παράδειγμα εφαρμογής του NER φαίνεται στην εικόνα 2.28

Εικόνα 2.28: Παράδειγμα εφαρμογής Named Entity Recognition

2.3.1.5 Relation Extraction

Αφού εντοπισθούν τα Named Entities τότε πιθανώς να ενδιαφέρει και ο εντοπισμός των σχέσεων αυτών. Το πρόβλημα αυτό φιλοδοξεί να λύσει το Relation Extraction. Το Re- lation Extraction δέχεται ως είσοδο την έξοδο του NER. Κατά το Relation Extraction, ελέγχονται πλειάδες (Χ,α,Y), όπου Χ,Y named entities και ”α” το κείμενο μεταξύ τους ή γύρω τους. Συγκεκριμένα ελέγχεται αν το ”α” αποτελεί ή περιέχει σχέση μεταξύ των X,Y. Αποτέλεσμα εφαρμογής του Relation Extraction είναι οι εντοπισμένες σχέσεις μεταξύ των named entities όπως φαίνεται παρακάτω [ORG: 'DDB Needham'] 'in' [LOC: 'New York']

Η συνολική διαδικασία του IE συνοψίζεται στην εικόνα 2.29.

Εικόνα 2.29: Η διαδικασία του Information Extraction Κεφάλαιο 2. Υπόβαθρο 44

2.3.2 Άλλα εργαλεία NLP

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

2.3.2.1 Κανονικές εκφράσεις (Regular Expressions)

Οι κανονικές εκφράσεις είναι συμβολοσειρές που περιγράφουν μία γλώσσα. Προέρχονται από την επιστήμη της Θεωρίας των Υπολογισμών. Στις γλώσσες προγραμματισμού οι συμβολοσειρές οριοθετούνται από δύο πλάγιες καθέτους, ”/”. Τα σύμβολά τους είναι χαρακτήρες. Οι δυνατοί χαρακτήρες ορίζονται από τυποποιήσεις όπως ASCII και Unicode. Κάποιοι χαρακτήρες έχουν συντακτικό ρόλο στην κανονική έκφραση. Παραδείγματος χάρη η πλάγια κάθετος οριοθετεί την έκφραση, ενώ ο χαρακτήρας * σημαίνει ”από 0 έως άπειροι χαρακτήρες”. Παρακάτω παραθέτουμε μερικά ενδεικτικά παραδείγματα κανονικών εκφράσεων (”ε” είναι το σύμβολο του κενού)[18]: • /a|b*/ το οποίο σημαίνει ”a ή από 0 έως άπειρες φορές το b” και παράγει το σύνολο ε, ”a”, ”b”, ”bb”, ”bbb”, … • /(a|b)*/ το οποίο σημαίνει ”συμβολοσειρές μόνο με a ή b, από 0 έως άπειρες φορές το καθένα” και παράγει το σύνολο ε, ”a”, ”b”, ”aa”, ”ab”, ”ba”, ”bb”, ”aaa”, … • /dog/ το οποίο σημαίνει απλά ”η συμβολοσειρά dog” • /Hello$/ το οποίο σημαίνει ”η πρόταση πρέπει να τελειώνει με την λέξη Hello” Οι κανονικές εκφράσεις μας επιτρέπουν να ελέγξουμε, αν ένα σύνολο χαρακτήρων που περιγράφει η κανονική έκφραση, εμφανίζεται σε ένα κείμενο.

2.3.2.2 Λίστες λέξεων ή φράσεων

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

2.3.2.3 nltk

Το λογισμικό της διπλωματικής είναι γραμμένο σε python version 3.5. Στην python η de facto βιβλιοθήκη για NLP είναι το nltk7. Το nltk συγκεντρώνει πλήθος εργαλείων NLP, όπως για παράδειγμα όλη την διαδικασία του Information Extraction που αναλύθηκε στην ενότητα 4.1. Μεταξύ άλλων αξιοποιεί το έργο γνωστών ερευνητικών ομάδων και οργανισμών όπως το Stanford Language Processing Group8 και το Wordnet9.

7http://www.nltk.org/ 8http://nlp.stanford.edu/ 9https://wordnet.princeton.edu/ 10https://www.ling.upenn.edu/courses/Fall_2003/ling001/penn_treebank_pos.html Κεφάλαιο 2. Υπόβαθρο 45

Εικόνα 2.30: Αλφαβητική λίστα POS Tags του Penn Treebarnk project10 46 Κεφάλαιο 3

Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος

3.1 Σχετική βιβλιογραφία

Όπως έχουμε πει, ο στόχος της διπλωματικής είναι να μετατρέψουμε απαιτήσεις για RESTful APIs σε OpenAPI Specification. Οι απαιτήσεις είναι γραμμένες σε Gherkin γλώσσα. Επειδή το τελικό προϊόν είναι το OpenAPI Specification (ειδικό), αναμενόμενο ήταν να μην υπάρχει άμεσα σχετική βιβλιογραφία. Μάλιστα το γεγονός αυτό εκτιμήθηκε ότι προσδίδει σχεδιαστικές ελευθερίες στην υλοποίηση. Σε κάθε περίπτωση διακρίνονται τα εξής βιβλιογραφικά αντικείμενα: 1. Εφαρμογή μηχανισμών NLP σε κείμενο λειτουργικών απαιτήσεων για εξαγωγή τεχνικών χαρακτηριστικών 2. Ανάπτυξη Web RESTful APIs με Gherkin

3.1.1 Εφαρμογή μηχανισμών NLP σε κείμενο λειτουργικών απαιτήσεων για εξαγωγή τεχνικών χαρακτηριστικών

Όλα τα σχετικά κείμενα πάνω στο θέμα έχουν ένα κοινό χαρακτηριστικό: Τον διαχωρισμό των λέξεων και των φράσεων μιας πρότασης σε εννοιολογικές ομάδες. Οι εννοιολογικές ομάδες αποφασίζονται από τον σχεδιαστή. Η επιλογή τους εξαρτάται από τις εκάστοτε ανάγκες. S-CASE Το S-CASE[22] είναι ένα ευρωπαϊκό έργο στο οποίο συμμετέχει το ISSEL Lab Group (στο οποίο εκπονήθηκε η παρούσα διπλωματική εργασία). Αντικείμενο του έργου είναι η ανάπτυξη εργαλείων, τα οποία έχουν στόχο την μείωση του κόστους και του χρόνου υλοποίησης λογισμικού. Στο πλαίσιο του προγράμματος αναπτύχθηκαν μεθοδολογίες αξιοποίησης NLP μηχανισμών σε κείμενα απαιτήσεων. Η απαιτήσεις δεν είναι γραμμένες σε γλώσσα Gherkin αλλά έχουν την παρακάτω μορφή

The operator must be able to print the invoice.

Το κείμενο σηματοδοτείται χειροκίνητα από τον άνθρωπο, όπως φαίνεται στην Eικόνα 3.1. Η επισήμανση των απαιτήσεων βασίζεται σε εννοιολογικές ομάδες οι οποίες έχουν προ- αποφασιστεί. Οι ομάδες αυτές συνθέτουν ένα οντολογικό δέντρο όπως φαίνεται στην Eικόνα 3.2 Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 47

Το λογισμικό λαμβάνει ως είσοδο το σηματοδοτημένο κείμενο και με βάση την σηματοδότηση, εξάγει άμεσα ένα τεχνικό μοντέλο λογισμικού. NLP σε Gherkin Σχετικά με την εφαρμογή μηχανισμών NLP σε Gherkin κείμενο ενδεικτικά είναι τα [24] και [14]. Στις εργασίες αυτές αξιοποιούνται έτοιμα εργαλεία NLP όπως το Wordnet και ο Stanford Parser. Το κείμενο των λειτουργικών απαιτήσεων σηματοδοτείται με την τεχνική POS tagging. Σε πιο πολύπλοκο κείμενο εφαρμόζεται sentence chunking (εικόνα 3.3) ή/και εντοπίζονται τα dependencies (εικόνα 3.4) των λέξεων και φράσεων μεταξύ τους. Η έξοδος του NLP είναι τα pos tags,chunks και dependencies. Αυτά μαζί με το κείμενο αποτελούν το αρχικό μοντέλο, το οποίο δέχεται ως είσοδο ένα επόμενο λογισμικό. Το επόμενο λογισμικό αξιοποιεί τις πληροφορίες του NLP, προκειμένου να αποφασίσει την τεχνική φύση των λέξεων και των φράσεων.

3.1.2 Web API Development με Gherkin

Στην Ενότητα 2.2 αναλύθηκε μεταξύ άλλων και η μεθοδολογία BDD. Είδαμε δηλαδή πώς καταγράφονται απαιτήσεις λογισμικού σε γλώσσα Gherkin και πώς στην συνέχεια μετατρέπονται οι απαιτήσεις σε λογισμικό. Η μετατροπή μπορεί να γίνει με το χέρι ή με την βοήθεια ενός εργαλείου, όπως το Cucumber. Στην δική μας περίπτωση δεν μας ενδιαφέρει η μετατροπή από απαιτήσεις σε λογισμικό άμεσα, αλλά η μετατροπή από απαιτήσεις σε τυποποίηση. Παρά την διαφορετική αυτή προσέγγιση όμως, μας ενδιαφέρει πως οι μηχανικοί αξιοποιούν τα εργαλεία αυτά για να αναπτύσσουν APIs. Δηλαδή η καθημερινότητα ενός Agile/BDD software engineer που χρησιμοποιεί Gherkin. Προκειμένου να αποκτηθεί μία γενική εικόνα για το θέμα, πραγματοποιήθηκαν διαδικτυακές επικοινωνίες με τον Co Owner της Cucumber, Seb Rose και τον agile team mentor J.B. Rainsberger. Το θέμα της συζήτησης ήταν ”Πώς ένας μηχανικός λογισμικού χρησιμοποιεί σήμερα το BDD, το Cucumber και την Gherkin για να αναπτύξει APIs και λογισμικό γενικότερα”. Παρακάτω επισημαίνουμε τα βασικά συμπεράσματα που εξήχθησαν από τις συζητήσεις: • Οι απαιτήσεις του πελάτη για το λογισμικό μπορεί να προκύψουν από συζήτηση με τον ίδιο ή τεχνικούς εκπρόσωπούς του. Κατά την συζήτηση δεν γίνεται τεχνική καταγραφή των απαιτήσεων. Δηλαδή δεν συντάσσεται κείμενο Gherkin μαζί με τον πελάτη. Το γεγονός όμως ότι θα γραφεί κείμενο Gherkin βοηθάει τον μηχανικό να προάγει έναν τρόπο σκέψης στην συζήτηση με τον πελάτη. • Το Gherkin κείμενο δεν είναι τελικό. Υπάρχει συνεχόμενο feedback από και προς τον πελάτη, το οποίο αλλάζει διαρκώς τις απαιτήσεις. • Η καταγραφή τον απαιτήσεων σε φυσική γλώσσα δεν βοηθάει μόνο την συζήτηση με τον πελάτη αλλά και τους μηχανικούς μεταξύ τους. • Ένα εργαλείο, όπως αυτό που προτείνεται στην διπλωματική, θα ήταν χρήσιμο για έναν Agile μηχανικό λογισμικού. Ας επισημανθεί επίσης ότι ούτε οι Rose και Rainsberger είχαν στην διάθεσή τους παραδείγματα Gherkin γλώσσας για περιγραφή API απαιτήσεων. Επιβεβαίωσαν όμως ότι το BDD είναι μία από τις μεθοδολογίες η οποία αξιοποιείται για ανάπτυξη Web APIs. Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 48

Εικόνα 3.1: S-CASE: Επισήμανση απαιτήσεων[22] Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 49

Εικόνα 3.2: S-CASE: Οντολογικό δέντρο εννοιολογικών κλάσεων[22] Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 50

Εικόνα 3.3: Πρόταση σημασμένη με POS tags και chunks[24]

Εικόνα 3.4: Κείμενο σημασμένο με POS tags και structural dependen- cies[14] Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 51

3.2 Εξειδίκευση του προβλήματος: Ανάπτυξη Web APIs με την Gherkin και το OpenAPI Specification

Εξηγήσαμε τις βασικές έννοιες του REST, του Παγκόσμιου Ιστού, των REST APIs, των μεθοδολογιών ανάπτυξης λογισμικού και του Natural Language Processing. Είδαμε επίσης την υπάρχουσα έρευνα γύρω από το αντικείμενο της διπλωματικής. Πλέον μπορούμε να ορίσουμε το πλαίσιο σχεδίασης και να προτείνουμε ένα σύστημα που να απαντάει στο πρόβλημα που αντιμετωπίζουμε. Οι στόχοι της διπλωματικής είναι δύο: • Η απεικόνιση λειτουργικών απαιτήσεων των RESTful API σε Gherkin • Η συγγραφή βιβλιοθήκης ικανής να μετατρέπει κείμενο Gherkin σε OpenAPI Spec- ification

3.2.1 Agile RESTful API Development

Προκειμένου να πετύχουμε τον πρώτο στόχο, πρέπει να εξετάσουμε το πώς αναπτύσσονται τα Web APIs. Όπως έχουμε εξηγήσει, τα APIs αποτελούν μία χρήσιμη διεπαφή ενός συστήματος. Κατά την ανάπτυξη ενός API δεν είναι δεδομένο ότι αυτό το σύστημα υπάρχει. Έτσι διακρίνονται δύο περιπτώσεις σχεδίασης API. Αυτά τα οποία σχεδιάζονται με βάση ένα υπάρχων σύστημα και αυτά τα οποία σχεδιάζονται ταυτόχρονα με το σύστημα. Για παράδειγμα, μία υπάρχουσα ιατρική βάση δεδομένων με ασθένειες και φάρμακα μπορεί να αξιοποιηθεί περαιτέρω μέσω ενός API για τον σχεδιασμό εφαρμογών για γιατρούς. Από την άλλη ο σχεδιασμός μίας εφαρμογής κινητού τηλεφώνου για κλείσιμο ραντεβού με γιατρό σημαίνει το σχεδιασμό του API μαζί με το σύστημα. Διακρίνονται επίσης και δύο ακόμα κατηγορίες Web APIs: Τα APIs τα οποία απευθύνονται στους μηχανικούς του ίδιου του συστήματος (εσωτερική κατανάλωση) και τα APIs που απευθύνονται σε μηχανικούς εκτός του συστήματος (δημόσια APIs). Παράδειγμα της πρώτης κατηγορίας αποτελούν όλες οι υπηρεσίες του Παγκόσμιου Ιστού που συνοδεύονται από εφαρμογές επιτραπέζιου υπολογιστή ή κινητού. Για παράδειγμα το Dropbox1 δίνει στους μηχανικους ένα API για να σχεδιάσουν την Desktop εφαρμογή. Από την άλλη γνωστά παράδειγμα της δεύτερης κατηγορίας, τα λεγόμενα Public API, αποτελούν τα δημόσια API των Google2, Twitter3, Facebook4, YouTube5, Microsoft6, Amazon7 και πάρα πολλών άλλων εταιριών. Την δική μας περίπτωση αφορούν τα APIs, τα οποία σχεδιάζονται μαζί με το σύστημα και έχουν στόχο την εσωτερική κατανάλωση. Δηλαδή μας ενδιαφέρει η περίπτωση σχεδιασμού ενός συστήματος/υπηρεσίας από την αρχή και η αξιοποίησή του με εφαρμογές λογισμικού. Ο τελικός χρήστης θα έχει πρόσβαση στο σύστημα μέσω αυτών των εφαρμογών. Υπό αυτή την έννοια, ο μηχανικός που σχεδιάζει το Web API έχει στο μυαλό του 3 επίπεδα αφαιρετικότητας (εικόνα 3.5):

1https://el.wikipedia.org/wiki/Dropbox 2https://developers.google.com/apis-explorer/ 3https://dev.twitter.com/ 4https://developers.facebook.com/ 5https://developers.google.com/youtube/ 6https://www.microsoft.com/cognitive-services/en-us/apis 7https://developer.amazon.com/ Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 52

1. Το συνολικό σύστημα το οποίο βρίσκεται ”πίσω” από το API 2. Το κομμάτι του συστήματος το οποίο ”εκτίθεται” μέσα από το API και αφορά μηχανικούς λογισμικού 3. Την τελική εφαρμογή που προορίζεται για τον χρήστη

Εικόνα 3.5: Τα επίπεδα σχεδιασμού ενός API1

Συνεπώς αντί να σχεδιάζει για τον χρήστη, σχεδιάζει για τον μηχανικό λογισμικού εφαρμογής, έτσι ώστε ο δεύτερος να σχεδιάσει για τον χρήστη. Άρα έχουμε δύο κατηγορίες μηχανικών λογισμικού 1. Ο μηχανικός λογισμικού του συστήματος, τον οποίο αφορά το συνολικό σύστημα, συμπεριλαμβανομένων των όποιων API και τελικών χρηστών 2. Ο μηχανικός λογισμικού της εκάστοτε εφαρμογής, τον οποίο αφορά μόνο η συγκεκριμένη εφαρμογή, το API που αυτή χρησιμοποιεί και οι χρήστες της Οι μηχανικοί λογισμικού της 2ης κατηγορίας, είναι και αυτοί χρήστες του συστήματος. Η ιδιότητα αυτή προκύπτει από την φύση του Παγκόσμιου Ιστού ως πλατφόρμα εφαρμογών. Το εργαλείο που αναπτύσσουμε εμείς, αφορά τους μηχανικούς λογισμικού του συστήματος. Άρα πρέπει να ορίσουμε όσο γίνεται καλύτερα αυτό το πλαίσιο. Ένα άλλο σημείο προσοχής είναι το πώς αναπτύσσονται τα Web APIs ώστε να είναι REST- ful. Όπως αναφέραμε στην Ενότητα 2.1.3, το REST είναι ένα σετ κανόνων. Ως σετ κανόνων, δεν προσδιορίζει τον τρόπο με τον οποίο μπορούν να ακολουθηθούν αυτοί οι κανόνες. Ιδίως όταν οι κανόνες αυτοί δεν έχουν γραφεί αποκλειστικά για τον Παγκόσμιο Ιστό. Το γεγονός αυτό έχει διαπιστωθεί από την ερευνητική κοινότητα. Έτσι για παράδειγμα στα βιβλία Rest in Practise [31], RESTful Web Services [20] και RESTful Web APIs [19], σκιαγραφείται μία αρχιτεκτονική σχεδιασμού RESTful Web APIs. Η αρχιτεκτονική αυτή συγκεντρώνει τις παρακάτω αρχές: • Όλες οι πληροφορίες του συστήματος αντιμετωπίζονται ως πόροι Παγκόσμιου Ιστού • Τα ειδικά χαρακτηριστικά των πληροφοριών συνοψίζονται σε αναπαραστάσεις πόρων Παγκόσμιου Ιστού • Οι πόροι θα καθίστανται διαθέσιμοι προς αξιοποίηση μέσω URIs Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 53

• Το σύστημα είναι ανεξάρτητο των εφαρμογών. Δηλαδή οι εφαρμογές οφείλουν να συμπεριλαμβάνουν όλες τις απαραίτητες πληροφορίες για την διεκπεραίωση των αιτημάτων τους • Το ρήματα HTTP πρέπει να έχουν απλή ερμηνεία, όπως αυτονόητα ορίζεται από την λέξη τους. • Οι πόροι συνδέονται μεταξύ τους με hypermedia controls. Η πλοήγηση στο σύστημα διασφαλίζεται με το HATEOAS. Έτσι ισχύουν οι έννοιες Resource State και Appli- cation State • Τα αιτήματα HTTP χαρακτηρίζονται από safety ή/και idempotency Έτσι ακολουθώντας αυτή την λογική, η οποία περιστρέφεται γύρω από την έννοια των πόρων, ο σχεδιασμός μίας υπηρεσίας Παγκόσμιου Ιστού κατά REST γίνεται πιο ξεκάθαρος.

3.2.2 Λειτουργικές και μη, απαιτήσεις

Κατά την ανάπτυξη λογισμικού οι απαιτήσεις του συτήματος χωρίζονται σε λειτουργικές και μη. Οι λειτουργικές απαιτήσεις αφορούν την λειτουργία του συστήματος. Δηλαδή συνδέονται άμεσα με την κεντρική ιδέα του λογισμικού και προσπαθούν να την καταστήσουν ικανή να υλοποιηθεί. Έτσι στον σχεδιασμό π.χ. ενός e-shop, λειτουργικές απαιτήσεις αφορούν τους χρήστες, τα προϊόντα, τις παραγγελίες, τις πληρωμές κ.λ.π.. Οι λειτουργικές απαιτήσεις είναι αυτές που μπορούν κυρίως να συζητηθούν με τον πελάτη (customer domain). Από την άλλη, οι μη λειτουργικές απαιτήσεις αφορούν την λειτουργικότητα του συστήματος. Δηλαδή την δυνατότητά του να υποστηρίζει τις λειτουργίες του. Έτσι στο προηγούμενο παράδειγμα μη λειτουργικές απαιτήσεις είναι η ταχύτητα απόκρισης, η δυνατότητα να παραμένει το σύστημα ενεργό, η ασφάλεια, η προστασία των προσωπικών δεδομένων κ.λ.π.. Στο σύστημα της διπλωματικής, μας αφορά η καταγραφή των λειτουργικών απαιτήσεων. Μας ενδιαφέρει η συζήτηση με τον πελάτη, να είναι όσο το δυνατόν πιο κοντά στο τεχνικό του αντικείμενο. Οι λεπτομέρειες του συστήματος που δεν αφορούν την λειτουργία του, δεν πρέπει να ”φαίνονται” στον πελάτη.

3.2.3 Απαιτήσεις συστήματος

Με βάση τα παραπάνω, οι απαιτήσεις του συστήματος είναι οι ακόλουθες • REST-aware: Η τελική τυποποίηση πρέπει να περιγράφει μία RESTful υπηρεσία Παγκόσμιου Ιστού • Agile-friendly: Η διαδικασία ανάπτυξης λογισμικού με το εργαλείο πρέπει να υποστηρίζει το ευέλικτο μοντέλο ανάπτυξης λογισμικού • OAS-aware: Το τελικό προϊόν είναι το OpenAPI Specification, άρα η διαδικασία μετατροπής πρέπει προφανώς να περιορίζεται από τους κανόνες του • Η μετατροπή από Gherkin σε OpenAPI Specification πρέπει να γίνεται σε λογικά γρήγορο χρόνο. Δηλαδή αρκετά γρηγορότερα από το να γίνει χειροκίνητα Κεφάλαιο 3. Σχετική Βιβλιογραφία & Εξειδίκευση του προβλήματος 54

• Οι απαιτήσεις που θα καταγράφονται σε Gherkin πρέπει να είναι τύπου λειτουργικές • Το σύστημα πρέπει να λαμβάνει υπ’ όψιν ότι χρήστης του API είναι ένας μηχανικός λογισμικού • Possible to develop: Ο σχεδιασμός πρέπει να επιλύει τα προβλήματα που προκύπτουν από την μη τυποποίηση των εννοιών του Παγκόσμιου Ιστού και την πολυπλοκότητα του NLP Όσον αφορά την τελευταία απαίτηση, προκειμένου να εκπληρωθεί απαιτούνται κάποιοι συμβιβασμοί. Οι συμβιβασμοί αυτοί έχουν ως εξής και σχετίζονται με την έννοια ”Ομοιόμορφη Διεπαφή”: 1. Τα resources διακρίνονται σε single resources, collections και functions. Τα collections και τα functions έχουν διαφορά μόνο νοηματική, το λογισμικό του συστήματος δεν τα διακρίνει. Τα single resources έχουν παραμετροποιημένο path ως εξής: /books/{book_id}. Αντίθετα τα collections και τα functions έχουν απλό path ώς εξής: /books ή /search. Ένα resource μπορεί να έχει και απλό και παραμετροποιημένο path 2. Η λογική, ιεραρχική σχέση των resources μεταξύ τους, μπορεί να εμφανίζεται στο path τους 3. Τα ρήματα GET και DELETE δεν παίρνουν body κατά το HTTP αίτημα και μπορούν να έχουν path παράμετρο ή/και query παράμετρο 4. Το ρήμα POST μπορεί να πάρει μόνο body. 5. Το ρήμα PUT μπορεί να έχει και body και path παράμετρο και query παράμετρο 6. Τα υπόλοιπα ρήματα του HTTP είναι τεχνικής φύσεως και δεν μπορούν να απεικονισθούν σε κείμενο λειτουργικών απαιτήσεων 7. Τα πιθανά status codes ορίζονται εκ σχεδιασμού και προς το παρών περιορίζονται στα 200,201,202,400,401,404. Τα status codes πρέπει να συνοδεύονται από μήνυμα περιγραφής Επιπρόσθετα, όπως θίξαμε σε προηγούμενη ενότητα, χρήστης του συστήματος είναι και ο μηχανικός λογισμικού που θα χρησιμοποιήσει το API. Άρα το σύστημά μας πρέπει να λαμβάνει υπ΄ όψιν και τον μηχανικό που θα χρησιμοποιεί το API. Στην πράξη αυτό καλύπτεται, καταρχήν από το OpenAPI Specification, κατά δεύτερον από το REST και τις αρχές του Παγκόσμιου Ιστού και κατά τρίτον από τις λογικές συμβάσεις που αναφέραμε.

0http://academy.apigee.com/courses/elearning/digital-transformation/digital-transformation/ managing-it-change/getting-agile-apis 55 Κεφάλαιο 4

Μεθοδολογία & Υλοποίηση συστήματος

4.1 Μεθοδολογία

Στις δύο πρώτες υποενότητες αυτής της ενότητας, εξετάζουμε την μεθοδολογία με βάση την οποία σχεδιάστηκε ο τρόπος απεικόνισης REST απαιτήσεων σε Gherkin. Επίσης, στην τρίτη υποενότητα παρουσιάζουμε την μεθοδολογία ανάπτυξης του λογισμικού που υλοποιήθηκε στο πλαίσιο της διπλωματικής.

4.1.1 Τεχνικό επίπεδο της Gherkin

Το πρώτο πρόβλημα που αντιμετωπίσθηκε ήταν το θέμα της τεχνικής γλώσσας σε κείμενο Gherkin. Δηλαδή το ύφος της περιγραφής των απαιτήσεων του API. Παραδείγματος χάρη στο βιβλίο του Cucumber [32], Κεφάλαιο 121, προτείνεται η εξής περιγραφή ενός API σε Gherkin

Παράδειγμα 4.1: Παράδειγμα περιγραφής API κατά Cucumber Feature: Fruit list In order to make a great smoothie I need some fruit. Scenario: List fruit Given the system knows about the following fruit: | name | color | | banana | yellow | | strawberry | red | When the client requests GET /fruits Then the response should be JSON: """ [ {"name": "banana", "color": "yellow"}, {"name": "strawberry", "color": "red"} ] """

Βλέπουμε ότι γίνεται η επιλογή μίας τεχνικής γλώσσας, η οποία περιλαμβάνει HTTP ρήματα, paths και αναπαραστάσεις πόρων όπως η JSON. Το γεγονός αυτό σχολιάζεται στο blogpost http://gregbee.ch/blog/effective-api-testing-with-cucumber που εξακολουθεί μέχρι σήμερα να εμφανίζεται πρώτο στις αναζητήσεις με tags REST, Cucumber, Gherkin. Στο post αυτό επισημαίνεται ότι μία γλώσσα όπως η Gherkin, ίσως να χάνει το νόημα της όταν γίνεται τόσο τεχνική. Αξίζει να σημειωθεί ότι ένας από τους συγγραφείς του βιβλίου, ο Aslak Hellesoy, είχε σχολιάσει το καλοκαίρι του 2016 πώς το θέμα που θίγεται στο blog

1Το κεφάλαιο αυτό είναι το μόνο στο οποίο γίνεται αναφορά σε APIs και είναι σύντομο και ενδεικτικό Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 56

είναι σωστό και ότι το κεφάλαιο του βιβλίου θα επανεξετασθεί1. Οι υπόλοιπες αναφορές στο διαδίκτυο πάνω στο θέμα, παραπέμπουν στο debate μεταξύ χρήσης τεχνικής ή όχι γλώσσας και είναι ελάχιστες. Πάντως στην περίπτωση περιγραφής API στο Cucumber, ύστερα από την Gherkin καταγράφονται τα step definitions, όπως περιγράφεται στο Παράρτημα A. Άρα δεν χρειάζεται κάποια ιδιαίτερη μεθοδολογία μετατροπής της φυσικής γλώσσας σε κώδικα. Αντίθετα στην δικιά μας περίπτωση είναι βασικός μας στόχος, να μπορούμε να μετατρέψουμε με λογισμικό την φυσική γλώσσα σε τεχνικά χαρακτηριστικά. Άρα το ύφος της Gherkin, πρέπει να αποσαφηνιστεί σχεδιαστικά. Με βάση την μέχρι τώρα θεωρητική και τεχνική ανάλυση, κρίθηκε ότι εξυπηρετεί ένα ύφος κοντινότερο στον πελάτη. Παρ΄ όλο που ο πελάτης μπορεί να μην συμμετέχει άμεσα στην διαδικασία συγγραφής των απαιτήσεων σε Gherkin (ενότητα 3.1.2), η κοινή γλώσσα επικοινωνίας είναι δομικής σημασίας στο BDD και στην Agile φιλοσοφία γενικότερα. Περαιτέρω η υιοθέτηση τεχνικών όρων έχει τα εξής δύο μειονεκτήματα: Πρώτον, εφόσον το Gherkin κείμενο θα περιγράφει ακριβώς την τεχνική διαδικασία, η φυσική γλώσσα θα εμφανίζεται ως θόρυβος. Ένας μηχανικός που έχει την ικανότητα να περιγράψει όλες τις τεχνικές λεπτομέρειες του API σε Gherkin, θα μπορούσε κάλλιστα να συγγράψει κατευθείαν το OpenAPI Specification. Δεύτερον, οι απαιτήσεις του λογισμικού μετατροπής από Gherkin σε OpenAPI Specification, μειώνονται δραματικά διότι το βασικό μέλημα του λογισμικού θα είναι η απλή οργάνωση των τεχνικών χαρακτηριστικών στην τυποποίηση. Συνεπώς η χρήση τεχνικής γλώσσας απορρίφθηκε, διότι κρίθηκε ότι θέτει την διπλωματική εκτός στόχου.

4.1.2 Απεικόνιση REST σε Gherkin

Η επιλογή ύφους κοντινότερου στον πελάτη καθιστά την απεικόνιση του OpenAPI Speci- fication σε Gherkin πρόκληση για έναν βασικό λόγο. Δεδομένου ότι το τελικό προϊόν είναι το OpenAPI Specification, η ανάπτυξη του συστήματος που θα περιγράφεται στα feature files, θα ξεκινάει αναπόφευκτα από το API. Τα APIs γενικότερα και τα RESTful Web APIs ειδικότερα, είναι εξ’ ορισμού τεχνικές έννοιες. Έτσι αν και η ανάπτυξη λογισμικού οδηγούμενη από το API είναι μία θεμιτή μεθοδολογία, πρόβλημα αποτελεί η περιγραφή του API από τον πελάτη. Προκειμένου αυτό το πρόβλημα να αντιμετωπισθεί, αξιοποιήθηκε η βιβλιογραφία γύρω από το REST. Συγκεκριμένα οι βιβλιογραφικές παραπομπές [20], [31] και [19]. Όπως αναλύσαμε εκτενώς στην Ενότητα 2.1 τα δομικά στοιχεία του Παγκόσμιου Ιστού είναι τα resources, τα resource representations, τα URIs και το πρωτόκολλο HTTP. Επιπλέον επεξηγήσαμε την έννοια του Uniform Interface και του HATEOAS. Στις προαναφερθείσες βιβλιογραφικές παραμομπές τα παραπάνω αξιοποιούνται ώστε: 1. Να προταθεί μία μεθοδολογία ανάπτυξης RESTful Web APIs η οποία θα περιστρέφεται γύρω από τους πόρους 2. Η φιλοσοφία του HATEOAS να αντιστοιχιστεί σε πρωτόκολλα που ακολουθούν επιχειρίσεις και οργανισμοί 2.1.4.1 Οι ιδέες αυτές βασίζονται στην λογική ”Thinking in resources”, η οποία επίσης προτείνεται στην βιβλιογραφία. Αν και αυτή η λογική ακολουθείται για να χτιστεί μία αρχιτεκτονική σχεδίασης REST υπηρεσιών, ή ίδια λογική μπορεί να χρησιμοποιηθεί και αλλιώς: Μπορεί επίσης να αποτελέσει έναν τρόπο σκέψης κατά την περιγραφή του API. Αυτό διότι η έννοια του ”πόρου” είναι μία πολύ απλή έννοια, η οποία συνδέεται άμεσα

1Το σχόλιο αυτό δεν εμφανίζεται πλέον στην ιστοσελίδα (Φεβρουάριος 2017) Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 57

με την έννοια της πληροφορίας και άρα καθίσταται γρήγορα κατανοητή. Η έννοια του ”πόρου” είναι η απαραίτητη γέφυρα που χρειαζόμαστε για να πραγματοποιήσουμε την ομαλή απεικόνιση της φιλοσοφίας του REST σε Gherkin. Επιπρόσθετα του τρόπου σκέψης γύρω από τους πόρους, απευθείας μπορούμε να αξιοποιήσουμε την, παρουσιαζόμενη στην βιβλιογραφία, αντιστοίχιση του Hypermedia as the Engine of Application State στα Domain Application Protocols. Η επιτυχής σύλληψη της λογικής του επιχειρησιακού μοντέλου του πελάτη είναι ζωτικής σημασίας και άρα η ιδέα αυτή είναι ευπρόσδεκτη στο σύστημά μας. Τέλος όπως περιγράψαμε στην ενότητα 2.1.4.1, αποτέλεσμα μετάβασης στο DAP, είναι η αλλαγή του resource state και του application state. Επίσης στην ενότητα 2.2.2, αναδείξαμε πώς η λογική περιγραφής του User Story κατά Gherkin παρομοιάζεται με την λογική περιγραφή μία μηχανής καταστάσεων. Αυτή η φυσική σύνδεση μεταξύ Gherkin και HATEOAS, ολοκληρώνει την πλήρη απεικόνιση της φιλοσοφίας του REST σε Gherkin. Η τυποποίηση αυτής της απεικόνισης περιγράφεται αναλυτικά στην ενότητα 4.2.1.

4.1.3 Λογισμικό

Κατά την ανάπτυξη του λογισμικού μετατροπής από Gherkin σε OpenAPI Specifica- tion ακολουθήθηκε η Agile φιλοσοφία σχεδίασης. Πριν την ανάπτυξη του λογισμικού ολοκληρώθηκε ο γενικός σχεδιασμός της απεικόνισης REST σε Gherkin. Στην συνέχεια μελετήθηκε διεξοδικά το OpenAPI Specification. Από την μελέτη διαπιστώθηκε ότι υπάρχουν χαρακτηριστικά της τυποποίησης τα οποία είναι βασικά. Τέτοια είναι παραδείγματος χάρη τα paths, οι παράμετροι, τα HTTP ρήματα και οι HTTP απαντήσεις. Προκειμένου να έχουμε ένα valid OpenAPI Specification, αυτά τα χαρακτηριστικά πρέπει απαραίτητα να υπάρχουν. Έτσι δημιουργήθηκε ένα αρχικό backlog χαρακτηριστικών προς υλοποίηση. Στην συνέχεια ακολουθήθηκε η παρακάτω λογική: 1. Εισαγωγή ενός νέου χαρακτηριστικού του OpenAPI Specification προς υλοποίηση 2. Αποσαφήνιση περιοχών εμφάνισης του χαρακτηριστικού στο Gherkin κείμενο 3. Συγγραφή Gherkin που περιγράφει το χαρακτηριστικό 4. Συγγραφή κώδικα που διαβάζει προτάσεις του Gherkin κειμένου, όπου το χαρακτηριστικό εμφανίζεται 5. Συγγραφή κώδικα μηχανισμών επεξεργασίας φυσικής γλώσσας ο οποίος εντοπίζει το χαρακτηριστικό στις προτάσεις 6. Συγγραφή κώδικα ο οποίος οργανώνει το χαρακτηριστικό στην μορφή του OpenAPI Specification 7. Επανάληψη από το βήμα (1) Αφού υλοποιήθηκαν επιτυχώς τα paths, οι παράμετροι των path, των query και των body, τα HTTP ρήματα και οι HTTP απαντήσεις, με την παραπάνω λογική, ο σκελετός του κώδικα είχε διαμορφωθεί. Κατά την διαδικασία συγγραφής του κώδικα, στόχος ήταν οι εσωτερικές του λειτουργίες να είναι κατά το δυνατόν ανεξάρτητες (Agile φιλοσοφία). Αυτή η αρχή ακολουθήθηκε τόσο κεντρικά στο λογισμικό, όσο και εσωτερικά των αρχείων. Με βάση λοιπόν τον διαμορφωμένο και ανεξάρτητα δομημένο κώδικα, άρχισαν να προστίθενται νέα χαρακτηριστικά. Έτσι προστέθηκαν οι τύποι δεδομένων, τα HA- TEOAS links, τα μηνύματα των status codes, η ιεραρχία των resources, οι ρόλοι, οι μη υποχρεωτικές παράμετροι και άλλες ιδιότητες παραμέτρων, η προαιρετική περιγραφή Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 58

των σεναρίων, η οργάνωση παραμέτρων σε μοντέλα, η οργάνωση των ρόλων σε μοντέλα κ.α.. Όλα αυτά τα χαρακτηριστικά υλοποιήθηκαν με βάση την προαναφερθείσα σειρά βημάτων. Αφού υλοποιήθηκε ένας μεγάλος αριθμός χαρακτηριστικών του OpenAPI Specifica- tion, το λογισμικό αντιμετωπίσθηκε συνολικά σαν σύστημα. Έτσι γράφτηκε ξεχωριστός κώδικας τερματικού και ξεχωριστός κώδικας γραφικής διεπαφής. Η γραφική διεπαφή αν και λειτουργική δεν προχώρησε περαιτέρω διότι δεν εξυπηρετούσε κάποιον σκοπό. Επίσης γράφτηκε δυνατότητα εκτέλεσης χωρίς Gherkin αρχεία, αλλά με μοντέλα χαρακτηριστικών προηγούμενων εκτελέσεων. Επιπλέον προστέθηκε το χαρακτηριστικό απεικόνισης του API από τα HATEOAS links τα οποία εντοπίζονται. Τα παραπάνω συνοψίζουν την μεθοδολογία ανάπτυξης του λογισμικού. Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 59

4.2 Υλοποίηση Συστήματος

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

4.2.1 Απεικόνιση λειτουργικών απαιτήσεων REST συστήματος σε Gherkin: Resource Driven Development

Με βάση τις απαιτήσεις συστήματος και τους συμβιβασμούς, όπως ορίστηκαν στην ενότητα 3.2.3, αλλά και όσα περιγράφηκαν στις ενότητες 4.1.1 και 4.1.2, σχεδιάζεται και προτείνεται η μεθοδολογία Resource Driven Development (RDD) για την ανάπτυξη RESTful Web APIs. Κατά το Resource Driven Development, ο μηχανικός σκέφτεται με βάση τους πόρους που θα εκθέτει το σύστημά του μέσω ενός Web API. Η λογική αυτή σκέψης αφορά τόσο την οργάνωση της πληροφορίας όσο και την υλοποίηση του Domain Application Protocol. Τα δύο αυτά θέματα μπορούν να συζητηθούν με τον πελάτη και τον αφορούν άμεσα. Μάλιστα το DAP το γνωρίζει καλά μόνο ο πελάτης και άρα μόνο μέσω αυτού μπορεί να διαπιστωθεί αλλά και να επιβεβαιωθεί. Το DAP υλοποιείται μέσω του HATEOAS. Το Resource Driven Development ορίζει ότι: • Οι λειτουργικές απαιτήσεις του API περιγράφονται σε γλώσσα Gherkin. • Tα feature files ονομάζονται πλέον resource files και έχουν επέκταση .resource αντί .feature. Σε ένα resource file περιγράφεται ένα και μόνο ένα resource. Το resource που περιγράφεται στο resource file, δίνει και το όνομα στο αρχείο. Έτσι το book resource περιγράφεται στο αρχείο book.resource. • Τα σενάρια εντός του resource file περιγράφουν τα HTTP αιτήματα προς το API και την HTTP απάντηση από το API. Συγκεκριμένα στο When βήμα περιγράφεται το αίτημα και στο Then βήμα περιγράφεται η απάντηση. • Αποτέλεσμα πραγματοποίησης ενός σεναρίου είναι η πιθανή αλλαγή του resource state και του application state. Το application state είναι το σύνολο των δυνατών μεταβάσεων σε άλλα resources από το τρέχον resource. Οι μεταβάσεις αυτές διαφημίζονται στην απάντηση του API. Η διαφήμιση σε τεχνικό επίπεδο γίνεται με hypermedia controls και άρα με το HATEOAS. Έτσι στο Then βήμα μπορούν να περιγραφούν τέτοιες μεταβάσεις. • Οι όποιες παράμετροι περιγράφονται είτε στο κείμενο των βημάτων των σεναρίων, είτε σε πίνακες των βημάτων των σεναρίων. Αν οι παράμετροι περιγράφονται σε πίνακα τότε μπορούν να προσδιορισθούν και οι τύποι τους, με παράδειγμα. Αν πρόκειται για αριθμούς, τότε μπορούν να περιγραφούν και οι μέγιστες και οι ελάχιστες τιμές τους. • Η λογική, ιεραρχική, σχέση των resources μπορεί προαιρετικά να περιγραφεί στο ”Background”. • Ρόλοι/χρήστες του API και τα δικαιώματα αυτών, μπορούν να περιγραφούν μόνο σε Given βήματα είτε στο ”Background” είτε στα σενάρια. Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 60

Στην συνέχεια θα εξετάσουμε αναλυτικά το RDD με παραδείγματα. Paths Τα paths στο RDD δεν περιγράφονται στο Gherkin κείμενο εξ’ ολοκλήρου. Επειδή ακολουθείται η λογική περιγραφής ανά πόρο, όλες οι βάσεις των path προκύπτουν από τα ονόματα των πόρων, άρα των αρχείων. Αυτό που χρειάζεται να περιγραφεί είναι οι ενδεχόμενες παράμετροι το path (βλ. πιο κάτω). Operations Τα operations, δηλαδή τα HTTP ρήματα, περιγράφονται στην πρόταση του σεναρίου που αρχίζει από When. Η περιγραφή τους γίνεται με το ρήμα της πρότασης. Το ρήμα αυτό αντιστοιχεί με λογικό τρόπο σε ένα operation. Για τον λόγο, αυτό ο χρήστης του RDD παροτρύνεται στην χρήση ρημάτων, τα οποία έχουν την σημασία της ”δημιουργίας” ή της ”διαγραφής” ή της ”προβολής” ή της ”ενημέρωσης” ενός πόρου. Έτσι, στο Παράδειγμα 4.2, το operation είναι το retrieve το οποίο αντιστοιχεί στο HTTP ρήμα GET.

Παράδειγμα 4.2: RDD: Παράδειγμα βήματος με http ρήμα When I retrieve a product by it`s name

Σε μία πρόταση μπορούν να επισημανθούν παραπάνω από ένα operations, όπως φαίνεται στο Παράδειγμα 4.3. Στην περίπτωση αυτή όλες οι παράμετροι και οι απαντήσεις του API που περιγράφονται, θα προστεθούν στα paths και των τριών ρημάτων, στις ανάλογες θέσεις τους (βλ. πιο κάτω)

Παράδειγμα 4.3: RDD: Παράδειγμα βήματος με περισσότερα το ενός http ρήματα When I try to delete, retrieve or edit the product

Parameters Οι παράμετροι μπορούν να προσδιοριστούν είτε εντός μίας πρότασης, με ουσιαστικό, είτε σε πίνακα ακριβώς κάτω από αυτήν. Για τις παραμέτρους μας ενδιαφέρουν τα εξής: • Η θέση τους (path, query, body, form) • Το όνομά τους • Ο τύπος τους • Το ενδεχόμενο format τους • Το αν είναι απαραίτητες ή όχι • Ο ενδεχόμενος περιορισμός τους ανάμεσα σε μέγιστα και ελάχιστα Προκειμένου να περιγραφεί η θέση των παραμέτρων, πρέπει να ληφθούν υπ’ όψιν οι συμβάσεις (1),(3),(4) και (5) της ενότητας 3.2.3 τις οποίες παραθέτουμε και εδώ για ευκολία: 1. Τα resources διακρίνονται σε single resources, collections και functions. Τα collec- tions και τα functions έχουν διαφορά μόνο νοηματική, το σύστημα δεν τα διακρίνει. Τα single resources έχουν παραμετροποιημένο path ως εξής: /books/{book_id}. Αντίθετα τα collections και τα functions έχουν απλό path ώς εξής: /books ή /search. Ένα resource μπορεί να έχει και απλό και παραμετροποιημένο path Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 61

2. Τα ρήματα GET και DELETE δεν παίρνουν body κατά το HTTP αίτημα και μπορούν να έχουν path παράμετρο ή/και query παράμετρο 3. Το ρήμα POST μπορεί να πάρει μόνο body. 4. Το ρήμα PUT μπορεί να έχει και body και path παράμετρο και query παράμετρο Επισημαίνουμε ότι παράμετροι στο κείμενο, οι οποίες έχουν ακριβώς το ίδιο όνομα με έναν πόρο ή τον πληθυντικό αυτού, δεν αντιμετωπίζονται ως παράμετροι. Τέτοιες παράμετροι θα πρέπει να τοποθετούνται σε πίνακα. Η θέση των παραμέτρων προσδιορίζεται από την περιγραφή του When βήματος. Οι παράμετροι που θέλουμε να εμφανίζονται στο path, πρέπει να δηλώνονται μία και μόνο μία φορά στην πρώτη πρόταση του When βήματος ή στον πίνακα της πρώτης πρότασης του When βήματος. Και στις δύο περιπτώσεις δεν πρέπει να εμφανίζονται άλλες παράμετροι. Στο Παράδειγμα 4.4 βλέπουμε τρόπους περιγραφής path παραμέτρου.

Παράδειγμα 4.4: RDD: παράμετροι στο path When I retrieve the basket by it`s id

When I retrieve the basket by it`s id |id|130|

When I retrieve the basket |id|120|

Επισημαίνουμε ότι: • Αν το ρήμα της πρότασης περιγράφει operation τύπου GET, PUT, DELETE • Αν σε όλα τα βήματα του When δεν περιγράφονται άλλες παράμετροι • Αν σε κανένα άλλο σημείο του resource file δεν περιγράφονται path παράμετροι τότε μία id path παράμετρος θα υποτεθεί. Επίσης υπενθυμίζουμε ότι το POST δεν παίρνει path. Αν οι παράμετροι των GET, DELETE είναι παραπάνω από μία, τότε αυτές μπορούν να τοποθετηθούν σε query. Παραδείγματα query φαίνονται στο Παράδειγμα 4.5.

Παράδειγμα 4.5: RDD: παράμετροι σε query When I retrieve a product list by it`s id And I filter the results by name and category

When search for a product by it`s date and it`s name | date | 12/04/2017 | | name | `bike` |

When I search for a test And I specify a date range | start date | 12/04/2017 03:05 | | end date | 12/04/2017 12:05 |

When I delete a registration | client_names | [`John`,`Nick`] | maximum of 10 | | client_surnames | [`Andrew`,`Rose`] | maximum of 10 | Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 62

Στην περίπτωση του PUT, όταν θέλουμε να έχει και path και query και body param- eters, τότε πρέπει υποχρεωτικά το query να περιγραφεί σε πίνακα και να αναγράφεται στην πρόταση του βήματος η λέξη ’query’. Αν και η περίπτωση είναι εξαιρετική, υποστηρίζεται. Όταν περιγράφουμε POST ή PUT, τότε μπορούμε να περιγράψουμε body παραμέτρους. Στην περίπτωση του PUT, εφόσον οι περιγραφόμενες παράμετροι είναι περισσότερες από μία και δεν έχουν επισημανθεί ως query, αυτομάτως τοποθετούνται στο body. Αντίθετα στο POST, όλες οι παράμετροι τοποθετούνται πάντα στο body (με βάση τις συμβάσεις). Παράδειγμα body παραμέτρων φαίνεται στο Παράδειγμα 4.6.

Παράδειγμα 4.6: RDD: παράμετροι σε body When I submit products to the basket | name | `Laptop` | | | qt | 5 | maximum of 10 and minimum of 2 |

Όσον αφορά τους τύπους των παραμέτρων, οι παράμετροι που εντοπίζονται σε προτάσεις, αντιμετωπίζονται ως ’string’. Εξαίρεση αποτελεί η λέξη ’id’ όπου εντοπίζεται ώς ’int32’. Για να εντοπισθεί μία παράμετρος σε μία πρόταση πρέπει, όπως είπαμε, να είναι ουσιαστικό της πρότασης. Η περιγραφή τύπων των παραμέτρων μπορεί να γίνει σε έναν Gherkin πίνακα, όπως έχει φανεί στα έως τώρα παραδείγματα. Σε ένα τέτοιο πίνακα μπορεί να δοθεί ένα ενδεικτικό παράδειγμα τιμής της παραμέτρου, από το οποίο θα εξαχθεί ο τύπος δεδομένου. Ενδεικτικό παράδειγμα σημαίνει ότι για να εντοπισθεί π.χ. ότι η παράμετρος είναι δεκαδικό νούμερο, πρέπει το παράδειγμά της να είναι 10.1 και όχι 10. Από τύπους δεδομένων του Ope- nAPI Specification υποστηρίζονται: ’string’, ’integer’, ’number’, ’file’, ’date’, ’date-time’, ’boolean’, ’password’, ’array’ και ’file’. Επίσης στον πίνακα μπορεί να περιγραφεί η μέγιστη και η ελάχιστη τιμή της παραμέτρου (μήκος αν είναι ’string’, μέγεθος αν είναι πίνακας). Αν τα μεγέθη της παραμέτρου περιορίζονται από και μέγιστο και ελάχιστο, τότε αρκεί η επισήμανση, οπουδήποτε εντός του κελιού, των δύο αριθμητικών ορίων. Αντίθετα αν περιορίζονται από μόνο ένα όριο, τότε πρέπει να δίνεται μία ενδεικτική λέξη ή φράση που περιγράφει αν είναι μέγιστο ή ελάχιστο, π.χ. ’can’t be greater than’. Τέλος, στην παρούσα έκδοση του λογισμικού, ο πίνακας πρέπει να ακολουθεί μία λογική. Αυτή είναι ότι η πρώτη γραμμή/στήλη θα έχει τα ονόματα των παραμέτρων, η δεύτερη τα παραδείγματα και η τρίτη τα μέγιστα/ελάχιστα. Οι πίνακες παραμέτρων μπορούν να έχουν πολλές μορφές όπως φαίνεται στα παραδείγματα 4.7-4.11 Παράδειγμα 4.7: RDD είδη πινάκων: Πίνακας με παραμέτρους στην πρώτη στήλη και παραδείγματα στην δεύτερη | name | `bag` | | size | 5 | | color | `blue` | | on_sale | true | | collection | [1 2 3 4] |

Παράδειγμα 4.8: RDD είδη πινάκων: Πίνακας με παραμέτρους στην πρώτη γραμμή και παραδείγματα στην δεύτερη | name | description | category | | `bag` | `great bag` | `sports` | Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 63

Παράδειγμα 4.9: RDD είδη πινάκων: Πίνακας μόνο με ονόματα παραμέτρων |name|price|

Παράδειγμα 4.10: RDD είδη πινάκων: Πίνακας με μία παράμετρο |order_document|file|

Παράδειγμα 4.11: RDD είδη πινάκων: Πίνακας με μέγιστα και ελάχιστα | name | `Laptop` | | | qt | 4 | maximum of 10 and minimum of 2 |

Εκτός των τύπων, το RDD δίνει την δυνατότητα οι body παράμετροι να οργανώνονται σε μοντέλα. Πέρα από τα μοντέλα που θα δημιουργήσει το σύστημα αυτόματα, ο χρήστης του RDD μπορεί να ονοματίσει ο ίδιος ένα πίνακα και έτσι να τον οργανώσει σε ένα μοντέλο. Προκειμένου ένα πίνακας που προορίζεται για body να οργανωθεί σε μοντέλο, πρέπει η πρόταση η οποία τον περιγράφει, να τελειώνει με άνω κάτω τελεία (:). Όταν η πρόταση τελειώνει με άνω κάτω τελεία, το σύστημα θα αναζητήσει ένα ουσιαστικό (ακόμη και με ίδιο όνομα με τα resources) στην πρόταση περιγραφής του πίνακα, και θα δώσει το όνομά του ως όνομα του μοντέλου. Με αυτόν τον διακριτικό τρόπο ο χρήστης του RDD μπορεί να κάνει χρήση μοντέλων χωρίς να επιβαρύνει τεχνικά το κείμενο. Παράδειγμα περιγραφής μοντέλου φαίνεται στο Παράδειγμα 4.12.

Παράδειγμα 4.12: RDD: περιγραφή μοντέλου When I update the product: | name | `bag` | | description | `great bag` | | category | `sports` |

Τέλος οι παράμετροι μπορεί να είναι υποχρεωτικές ή όχι. Σε ένα API, οι παράμετροι είναι υποχρεωτικές όταν πρέπει όλες να συμμετέχουν είτε στο HTTP αίτημα είτε στην HTTP απάντηση. Το RDD δίνει την δυνατότητα να περιγράφεται ένα HTTP αίτημα και οι ενδεχόμενες HTTP απαντήσεις του παραπάνω από μία φορές. Έτσι οι παράμετροι που εμφανίζονται σε όλα τα ίδια HTTP αιτήματα και σε όλες τις ίδιες HTTP απαντήσεις, διαπιστώνονται ως required1. Με αυτό τον τρόπο, ο χρήστης του RDD μπορεί να ξανά περιγράψει ένα σενάριο, μόνο για να δείξει ποιες μεταβλητές είναι υποχρεωτικές. Τέλος επισημαίνουμε ότι η διάκριση των HTTP απαντήσεων δεν γίνεται με βάση το εκάστοτε HTTP αίτημα που τις προκαλεί αλλά με βάση το status code (βλ. παρακάτω). Άρα υποχρεωτικές παράμετροι στην HTTP απάντηση είναι όσες εμφανίζονται στα ίδια oper- ation με τα ίδια status code. Responses Η περιγραφή των HTTP απαντήσεων ξεκινάει από την πρόταση του βήματος Then και τις προτάσεις And που την ακολουθούν. Σε μία τέτοια πρόταση μπορούν να περιγραφούν παράμετροι, status codes και HATEOAS links. Για τις παραμέτρους ισχύει, ό,τι ισχύει και για τις body παραμέτρους των operation. Σχετικά με τα status code υπενθυμίζουμε την σύμβαση (7):

1Επισημαίνεται ότι σε αυτή την περίπτωση τα body τύπου μοντέλα, αντιμετωπίζονται ως μία παράμετρος. Το αν οι παράμετροι του μοντέλου είναι υποχρεωτικές, δεν εξετάζεται Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 64

”Τα πιθανά status codes ορίζονται εκ σχεδιασμού και προς το παρών περιορίζονται στα 200,201,202,400,401,404. Τα status codes πρέπει να συνοδεύονται από μήνυμα περιγραφής” Έτσι ορίζουμε ότι, προκειμένου να εντοπισθεί ένα status code σε μία πρόταση, τότε πρέπει να αναγράφεται στην πρόταση ή λέξη ’message’ και η περιγραφή του να είναι εντός εισαγωγικών. Η περιγραφή αυτή πρέπει να είναι νοηματικά παραπλήσια με το code. Π.χ. ’success’, ’ok’, ’updated’, ’deleted’, ’retrieved’, ’canceled’ για 200 και ’not found’, ’doesn’t exist’, ’does not exist’, ’unable to find’, ’can’t find’ για 404. Αν δεν εντοπισθεί status code σε κανένα βήμα, ανατίθεται το ’default’, όπως επιτρέπει το OpenAPI Specifi- cation. Επισημαίνουμε ότι όλες οι παράμετροι και τα HATEOAS links που εντοπίζονται, θα αντιστοιχούν σε αυτό το status code. Παράδειγμα status code δίνεται στο Παράδειγμα 4.13. Στο παράδειγμα αυτό εντοπίζεται το status code Bad Request, 400.

Παράδειγμα 4.13: RDD: status code When I submit a wrong payment for an order Then I should see a message saying `wrong amount`

Όσον αφορά τα HATEOAS links, αυτά περιγράφονται με επισήμανση του ρήματος μετάβασης και του πόρου μετάβασης. Έτσι στην πρόταση πρέπει να αναγράφεται και το ρήμα αλλά και ακριβώς το όνομα του πόρου μετάβασης. Σε τέτοιο ίδιου προτάσεις δεν αναζητούνται παράμετροι ή status codes. Η πρόταση δεν πρέπει να έχει πίνακα από κάτω. Παράδειγμα HATEOAS link φαίνεται στο Παράδειγμα 4.14. Τα links που εντοπίζονται είναι τα POST payment, GET order, DELETE order, PUT order.

Παράδειγμα 4.14: RDD: HATEOAS links Scenario: submit new order # Given that I have a basket with products When I submit an order |order_document|file| Then a new order is created "Successfully" And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Path hierarchies Η ιεραρχία εντός ενός path μπορεί να προσδιοριστεί στο Background του resource file σε βήμα Given. Εκεί πρέπει να αναφέρεται επακριβώς το όνομα ενός άλλου resource. Επίσης πρέπει να προσδιορίζεται και μία παράμετρος σύνδεσης (η οποία θα είναι path παράμετρος). Η παράμετρος αυτή πρέπει υποχρεωτικά να επισημαίνεται τουλάχιστον μία φορά ως path παράμετρος στο resource file του resource σύνδεσης (αν δεν επισημαίνεται στο resource file του resource σύνδεσης, τότε το αποτέλεσμα μπορεί να μην είναι το επιθυμητό). Το resource που θα εντοπισθεί στην πρόταση, θα προστεθεί ως μεγαλύτερο path hierarchy, από το resource στου οποίου το resource file περιγράφεται το Back- ground. Μεγαλύτερη ιεραρχία σημαίνει αριστερά του τρέχοντος path. Αν θέλουμε να συμβαίνει το ανάποδο, τότε η ιεραρχία πρέπει να περιγραφεί στο άλλο resource file. Παράδειγμα περιγραφής ιεραρχίας φαίνεται στο Παράδειγμα 4.15. Στο παράδειγμα αυτό, δεδομένου ότι το resource file είναι το ’payment’, το path προκύπτει ’/order/id/payment’ Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 65

Παράδειγμα 4.15: RDD: path hierarchies Background: Given the id of an unpaid order

Roles Οι ρόλοι μπορούν να περιγραφούν στο Background του resource file, σε βήμα Given, ή σε βήμα Given ενός σεναρίου. Σε αυτές τις προτάσεις, ως ρόλοι αντιμετωπίζονται τα ουσιαστικά. Στην περίπτωση που οι ρόλοι αναφέρονται στο Background, τότε δεν πρέπει να περιγράφονται ονόματα resources στην πρόταση αναφοράς. Αν περιγράφονται, τότε η πρόταση μπορεί να αντιμετωπισθεί ως πρόταση με ιεραρχία. Ένας ρόλος που περιγράφεται σε Background, αφορά όλα τα σενάρια. Έτσι έχει δικαιώματα σε ό,τι περιγράφει το resource file. Αντίθετα ένας ρόλος που περιγράφεται σε σενάριο έχει δικαιώματα μόνο επί του σεναρίου. Παράδειγμα ρόλου φαίνεται στο Παράδειγμα 4.16.

Παράδειγμα 4.16: RDD: roles Scenario: remove product from site Given I am logged in as administrator When I delete a product by it`s name Then I should see the deleted product | name | "bag" | | size | 5 | | color | "blue" | | on_sale | true | | collection | [1 2 3 4] |

Παρακάτω παρατίθενται και δύο συνολικά παραδείγματα του RDD.

Παράδειγμα 4.17: RDD: Ένα resource file Feature: pay for order

# POST /order/{order_id}/payment

Background: Given an unpaid order`s id

Scenario: pay for order When I submit a payment for an order | amount | 28.2 | | date | 8/2/2017 12:32 | Then I should be prompted to view the order

Scenario: pay for order less or more money When I submit a wrong payment for an order Then I should see a message saying "wrong amount" And I should be prompted to submit a payment And I should be prompted to view the order

Στο παράδειγμα αυτό περιγράφεται το resource ’payment’ ενός υποθετικού ηλεκτρονικού καταστήματος. Στο resource αυτό αποτυπώνεται η επιχειρηματική δραστηριότητα της πληρωμής. Περιγράφονται δύο σενάρια, αυτό της επιτυχούς και αυτό της εσφαλμένης πληρωμής. Στο σενάριο της επιτυχούς πληρωμής, παρατίθεται ένας πίνακας με τις ηλεκτρονικές πληροφορίες που ενδιαφέρουν την πληρωμή. Στον πίνακα αυτό Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 66

παρατίθενται και ενδεικτικά παραδείγματα. Συγκεκριμένα ότι η πληρωμή είναι ένας δεκαδικός αριθμός και ότι μας ενδιαφέρει η πλήρης ημερομηνία πληρωμής. Επιπλέον παρατηρούμε ότι τα δύο σενάρια περιγράφουν όμοια αιτήματα προς το API. Δηλαδή την αποστολή στοιχείων πληρωμής. Όμως αν και τα αιτήματα είναι σχεδόν ίδια, οι απαντήσεις από το API είναι διαφορετικές. Στην περίπτωση επιτυχούς πληρωμής, προτείνεται η προβολή της παραγγελίας. Αντίθετα στην περίπτωση λανθασμένης πληρωμής, εμφανίζεται σχετικό μήνυμα καθώς και δύο προτροπές: αποστολή νέας πληρωμής ή προβολή παραγγελίας. Οι προτροπές αντιστοιχούν στο Domain Application Protocol του καταστήματος το οποίο για το API σημαίνει hypermedia controls. Αντίστοιχα το λανθασμένο μήνυμα αντιστοιχεί σε αποτυχημένο status code. Στο παράδειγμα 4.18 φαίνεται ένα resource στο οποίο περιγράφονται και τα 4 δυνατά op- erations προς το API. Δηλαδή τα POST, PUT, GET, DELETE.

Παράδειγμα 4.18: RDD: Πλήρες resource file Feature: order products

# POST /order # GET, PUT, DELETE /order/{order_id}

Scenario: submit new order # Given that I have a basket with products When I submit an order |order_document|file| Then a new order is created "Successfully" And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Scenario: cancel submitted order # Given I have ordered When I cancel the order Then I should see a success message saying "Order canceled" And I should be prompted to search for more products

Scenario: update unpaid order # Given I have ordered # And the order status is "unpaid" When I update the order with products |name|qt| Then I should see a success message saying "Order updated" And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Scenario: view unpaid order # Given that I have ordered When I request an order by it`s id Then I can view the details of the order |name|qt| And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 67

Scenario: view paid order # Given that I have ordered When I request an order by it`s id Then I can view the details of the order |name|qt| And I have the option to review the order

Scenario: order doesn`t exist # Given an order doesn`t exist When I request, delete or update that order Then I should see a message "That order doesn`t exist"

Βλέπουμε ότι στα σενάρια γίνεται να επισημαίνονται παραπάνω από ένα operations (σενάριο ’order doesn’t exist’). Επίσης παρατηρούμε ότι τα Given βήματα των σεναρίων παρατίθενται ως σχόλια. Τα συγκεκριμένα σχόλια δεν περιγράφουν ρόλους και άρα δεν έχουν νόημα για το RDD όπως έχει οριστεί. Προστέθηκαν όμως για να αναδείξουν το γεγονός ότι τα REST APIs είναι stateless. Παρά το γεγονός ότι το επιχειρησιακό πρωτόκολλο προϋποθέτει τα προϊόντα να βρίσκονται σε καλάθι, ο Roy Fielding μας λέει ότι αυτό δεν αφορά το API. Έτσι αν θέλουμε πρώτα να προστίθενται προϊόντα στο καλάθι και μετά να γίνεται η παραγγελία, πρέπει η μετάβαση στο resource ’order’ να καθίσταται δυνατή μόνο μέσω το resource ’basket’. Προκειμένου να επιτευχθεί αναγνωσιμότητα, αυτή η προϋπόθεση δύναται να επισημανθεί και με σχόλιο στην περιγραφή του resource ’or- der’. Τα resource files που συγγράφηκαν για την εκπόνηση της διπλωματικής παρατίθενται στο παράρτημα. Ο παραπάνω τρόπος συγγραφής απαιτήσεων κατά RDD τυποποιήθηκε και σε ένα έγγραφο στα αγγλικά. Το έγγραφο αυτό παρέχεται στους μηχανικούς για να μπορούν να χρησιμοποιήσουν το σύστημα της διπλωματικής. Το έγγραφο παρατίθεται στο παράρτημα D.

4.2.2 Gherkin2OAS

Με δεδομένη την παραπάνω σχεδίαση των resource files μπορούμε πλέον να περιγράψουμε το λογισμικό, το οποίο αναλαμβάνει την μετατροπή σε OpenAPI Specification. Το λογισμικό αυτό θα το αποκαλούμε Gherkin2OAS. Το Gherkin2OAS είναι γραμμένο σε γλώσσα python1 3.5. Προκειμένου να υλοποιηθεί και δεδομένου ότι δεν υπήρχαν έτοιμα gherkin feature files, σχεδιάστηκε με βάση την προηγούμενη ενότητα ένα ενδεικτικό eshop. Το eshop αποτελούταν από 5 resource files, τα ”product”, ”payment”, ”search”, ”order”, ”basket”. Κατά την συγγραφή του Gherkin2OAS, οι δοκιμές γινόταν με βάση αυτά τα resource files. Το Gherkin2OAS αποτελείται από τρεις βασικές λογικές μονάδες: 1. Preprocessor Ο preprocessor αναλαμβάνει την ανάγνωση των Gherkin resource file που έχουν συγγραφεί και την προετοιμασία τους για NLP. Τα αρχεία αυτά πρέπει είναι οργανωμένα σε έναν φάκελο, η θέση του οποίου δίνεται ως είσοδος στον prepro- cessor. Εντός του preprocessor εμφανίζονται δύο διαδικασίες προ-επεξεργασίας: Στην πρώτη, χρησιμοποιείται ο έτοιμος Gherkin Parser2. Στην συνέχεια γίνεται μία δεύτερη προ-επεξεργασία η οποία έχει στόχο την αφαίρεση της περιττής πληροφορίας

1https://www.python.org/ 2https://github.com/cucumber/gherkin Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 68

του Gherkin Parser και την προετοιμασία της πληροφορίας για NLP. Έξοδος του preprocessor είναι το preprocessed model. 2. NLP Engine Το NLP Engine είναι ο πυρήνας του λογισμικού. Είσοδός του είναι το preprocessed model. Στο NLP Engine πραγματοποιείται η εξαγωγή τεχνικών χαρακτηριστικών από το preprocessed model. Για να γίνει αυτό εφικτό αξιοποιείται η μεθοδολογία POS Tagging, τα regular expressions αλλά και λίστες λέξεων και φράσεων. Έξοδος του NLP Engine είναι το technical model. 3. Formatter Ο Formatter δέχεται ως είσοδο το technical model και αναλαμβάνει την μετατροπή του σε OpenAPI Specification. Στο ”μυαλό” του υπάρχουν όλες οι απαραίτητες πληροφορίες για το OpenAPI Specification. Έξοδος του Formatter είναι ένα αρχείο swagger.json ή swagger.yaml, το οποίο περιέχει το OpenAPI Specification Τεχνικές που εφαρμόζονται στο NLP Engine Το περιεχόμενο των resource files είναι έως ένα βαθμό ’προβλέψιμο’. Αυτό οφείλεται στο ότι 1. Τα resource files είναι γραμμένα σε γλώσσα Gherkin. Έτσι καταρχήν οι λέξεις κλειδιά της γλώσσας ορίζουν ένα πλαίσιο ελευθερίας. 2. Τα resource files περιγράφουν ένα RESTful Web API. Συνεπώς η αναμενόμενη ορολογία/φρασεολογία είναι σχετική μόνο με RESTful Web APIs. 3. Ο σχεδιασμός της απεικόνισης των απαιτήσεων RESTful Web APIs σε Gherkin, συμπεριλαμβανομένων των συμβάσεων, είναι τέτοιος ώστε να πληρεί την απαίτηση 7 του Gherkin2OAS (απαιτήσεις συστήματος, ενότητα 3.2.3). 4. Το όνομα του resource file, είναι και το όνομα του resource. Αυτή η σχεδιαστική πρωτοβουλία είναι μείζονος σημασίας, διότι επιλύει το πρόβλημα του εντοπισμού των resources στο κείμενο. Τα χαρακτηριστικά αυτά των resource files καθιστούν το έργο του NLP Engine εφικτό. Στόχος του NLP Engine είναι η κατά το δυνατόν ακριβέστερη εξαγωγή τεχνικών χαρακτηριστικών από το HTTP και η παράθεσή τους σε ένα μοντέλο χαρακτηριστικών. Τέτοια χαρακτηριστικά είναι: • Τα HTTP ρήματα • Οι όποιες παράμετροι εμφανίζονται στο HTTP αίτημα και στην HTTP απάντηση και τα τεχνικά τους χαρακτηριστικά • Το HATEOAS των HTTP απαντήσεων • Τα status codes και τα όποια μηνύματα αυτών • Η ιεραρχία των resources • Οι ρόλοι/χρήστες του API και τα δικαιώματα αυτών Στην συνέχεια περιγράφονται οι συναρτήσεις του NLP Engine. - resource_analysis Αποτελεί την κύρια συνάρτηση του υποσυστήματος. Δέχεται ώς είσοδο το προ επεξεργασμένο μοντέλο του preprocessor και επιστρέφει ως έξοδο ένα τεχνικό μοντέλο Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 69

χαρακτηριστικών. Στην Εικόνα 4.1 φαίνεται η μορφή της εισόδου. Αντίστοιχα στην Εικόνα 4.2 φαίνεται η γενική μορφή της εξόδου του της συνάρτησης. Στην θέση των μεταβλητών ’resource’ και ’operation’ μπαίνουν τα αντίστοιχα ονόματα των resources και των operations αυτών. Η resource_analysis εξετάζει ένα ένα τα resources και τα σενάρια αυτών. Συγκεκριμένα εντός ενός resource, εξετάζει πρώτα το Background και μετά τα Scenario. Στο Back- ground εντοπίζει ρόλους και ιεραρχία resources με την βοήθεια των συναρτήσεων de- tect_other_resources και detect_roles. Πρώτα αναζητείται ιεραρχία και αν δεν βρεθεί αναζητούνται ρόλοι. Στην συνέχεια εξετάζονται τα σενάρια. Σε κάθε σενάριο, αναλύεται πρώτα το βήμα Given μετά το When και μετά το Then. Στο βήμα Given αναζητούνται ρόλοι με την βοήθεια της detect_roles. Στην συνέχεια αναλύεται το βήμα When. Στο βήμα When εντοπίζονται οι παράμετροι κειμένου με την detect_parameters και τα operations με την detect_operations. Για όλες τις παραμέτρους γίνεται καταγραφή αριθμού εμφανίσεων, όπως επίσης γίνεται και καταγραφή εμφανίσεων HTTP αιτημάτων και HTTP απαντήσεων. Αν το operation του σεναρίου είναι GET, DELETE, PUT, επιχειρείται εντοπισμός path παραμέτρου. Αν το operation του σεναρίου είναι PUT ή POST επιχειρείται εύρεση μοντέλου με την βοήθεια της detect_model_name. Αν το operation του σεναρίου είναι PUT, επιχειρείται ειδικός εντοπισμός και καταγραφή query παραμέτρων. Όλες οι παράμετροι πινάκων εντοπίζονται με την βοήθεια της process. Για όλες τις παραμέτρους δίνεται προσοχή να μην καταγράφονται δύο φορές. Έπειτα αναλύεται το βήμα Then. Πρώτα γίνεται προσπάθεια εντοπισμού status code στα βήματα με την βοήθεια της detect_messages. Αν δεν εντοπισθεί, θεωρείται το ’default’ ως status code. Στην συνέχεια εντοπίζονται οι παράμετροι και τα HATEOAS links. Για τις παραμέτρους, τους τύπους αυτών και την εμφάνισή τους ισχύει ό,τι και στην ανάλυση του βήματος When. Τα HATEOAS links εντοπίζονται με την βοήθεια της detect_operations. Τα HATEOAS links καταγράφονται σε δύο μοντέλα γράφων, το ’resource_state’ και το ’state’ για μελλοντική απεικόνιση σημαντικών πληροφοριών. Το μοντέλο γράφου ’re- source_state’ καταγράφει τις μεταβάσεις από πόρο σε πόρο, ενώ το μοντέλο γράφου ’state’ καταγράφει τις μεταβάσεις από application state σε application state. Στιγμιότυπα των μοντέλων φαίνονται στις Εικόνες 4.3 και 4.4 αντίστοιχα. Την λειτουργία των γράφων θα την εξετάσουμε παρακάτω και στην Ενότητα 5.3.2. Αν το σενάριο έχει description, αυτό καταγράφεται Αφού έχουν αναλυθεί όλα τα resources, ορίζονται τα requirements τους με την βοήθεια της set_parameter_requirements. Εν τέλει η resource_analysis επιστρέφει το τεχνικό μοντέλο και τα μοντέλα γράφων. - detect_other_resources Εντοπίζει ονόματα resources σε μία πρόταση, πέραν αυτών που δίνονται ως ορίσματα - detect_roles Η συνάρτηση αυτή εντοπίζει ρόλους χρηστών με την βοήθεια NLP. Συγκεκριμένα την διαδικασία του IE έως το POS Tagging. Τα nouns αντιμετωπίζονται ως ρόλοι. Εμπεριέχει εσωτερικό μηχανισμό διάκρισης από πρόταση που περιγράφει ιεραρχία resources (οπότε και η εξεταζόμενη πρόταση δεν πρέπει να εξεταστεί). - detect_messages Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 70

Εικόνα 4.1: Gherkin2OAS: Preprocessor model

Επιχειρεί να εντοπίσει τύπους status codes και τα μηνύματα αυτών. Πρώτα αναζητά φράση σε εισαγωγικά με την βοήθεια της find_quoted_text. Εφόσον βρει, μετατρέπει τα κεφαλαία γράμματα σε μικρά και ελέγχει την ύπαρξη της φράσης σε λίστες λέξεων. Οι λίστες αυτές περιέχουν αντιστοιχίες γνωστών φράσεων με status codes. Τέτοιες λίστες φαίνονται στην εικόνα 4.5. Αν δεν βρεθεί αντιστοίχιση υιοθετείται το ’default’ status code, κατά το OpenAPI Specification και τυπώνεται προειδοποιητικό μήνυμα. - detect_operations Εντοπίζει operations σε πρόταση με την βοήθεια της detect_http_verbs. Στην περίπτωση του βήματος Then, οπότε και έχει κληθεί για την εύρεση βήματος μετάβασης ενός HA- TEOAS link, επιβεβαιώνει πρώτα ότι η πρόταση έχει τουλάχιστον ένα resource. - detect_parameters Εντοπίζει παραμέτρους κειμένου με την βοήθεια POS Tagging - detect_model_name Εντοπίζει ονόματα μοντέλων με την βοήθεια POS Tagging - detect_http_verbs Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 71

Εικόνα 4.2: Gherkin2OAS: nlp model

Εντοπίζει HTTP ρήματα με την βοήθεια POS Tagging και λιστών λέξεων ρημάτων HTTP, όπως φαίνεται στην Εικόνα 4.6. Καταγράφει και την φυσική λέξη του ρήματος (χρειάζεται στον hateoas γράφο). - plural_extend Επεκτείνει τα ονόματα των resources με τους πληθυντικούς αυτών - process Η συνάρτηση αυτή αναλύει έναν πίνακα παραμέτρων με την βοήθεια των figure_cell_type και detect_min_max_cell. Αρχικά διαπιστώνεται η μορφή του πίνακα. Οι πιθανές μορφές του πίνακα που ενδιαφέρουν εδώ είναι δύο: Πίνακας που έχει τα ονόματα των παραμέτρων στην πρώτη γραμμή και πίνακας που έχει τα ονόματα των παραμέτρων στην πρώτη στήλη. Εφόσον αυτό διαπιστωθεί, καταγράφονται οι τύποι, τα μέγιστα και ελάχιστα και τα παραδείγματα των παραμέτρων, εφόσον αυτά υπάρχουν. Η συνάρτηση περιέχει μηχανισμό ασφαλείας σε περίπτωση που η μορφή του πίνακα δεν προβλέπεται. - figure_cell_type Αναζητεί τον τύπο ενός κελιού πίνακα, όπως ζητήθηκε από την process. Η αναζήτηση βασίζεται στους υποστηριζόμενους τύπους δεδομένων, δηλαδή ’float’, ’int’, ’bool’, ’array’, ’password’, ’file’, date-time’, ’date’. Οι τύποι δεδομένων βρίσκονται με την βοήθεια των type_of_value, is_date,, is_array, is_quoted_text και is_data_type. Η συνάρτηση εντοπίζει επίσης το είδος του collection αν ο τύπος είναι ’array’. Επιπλέον έχει την δυνατότητα ορισμού format. Τέλος αν ο τύπος δεν μπορεί να εντοπισθεί, ορίζεται ως ’string’. - detect_min_max_cell Η συνάρτηση εντοπίζει μέγιστα και ελάχιστα στο δοθέν κελί με την βοήθεια της de- tect_numbers. Συγκεκριμένα, ανάλογα με τον τύπο του κελιού και το πλήθος των εμφανιζόμενων αριθμών, ορίζει και τις ανάλογες ιδίοτητες μεγίστου και ελαχίστου. Στην περίπτωση που έχει προσδιοριστεί μόνο ένα νούμερο, το περιεχόμενο του κελιού αναζητείται για γνωστές εκφράσεις μεγίστου και ελαχίστου με την βοήθεια της de- tect_phrase. Τέτοιες γνωστές φράσεις φαίνονται στην εικόνα 4.7. Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 72

Εικόνα 4.3: Gherkin2OAS: Παράδειγμα μοντέλου γράφου ’resource_state’

- detect_numbers Εντοπίζει νούμερα σε κείμενο με απλό text spliting και την βοήθεια της type_of_value. - set_parameter_requirements Η συνάρτηση αρχικά ορίζει όλες τις παραμέτρους ως μη required. Στην συνέχεια αναζητεί και συγκρίνει το πλήθος εμφάνισης των παραμέτρων με το πλήθος εμφάνισης των oper- ation και των HTTP απαντήσεων. Εφόσον είναι ίδιο, η παράμετρος είναι required. Η αναζήτηση αφορά όλων των ειδών της παραμέτρους (query, body και σε πίνακα ή όχι). Σημειώνεται πως ανεξάρτητα από αυτή την συνάρτηση, μία path παράμετρος είναι πάντα required. - detect_phrase Αναζητεί φράση σε κείμενο με regular expressions. - type_of_value Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 73

Εικόνα 4.4: Gherkin2OAS: Παράδειγμα μοντέλου γράφου ’state’

Εντοπίζει αριθμητικούς τύπος δεδομένων με την βοήθεια της έτοιμης συνάρτησης lit- eral_eval του πακέτου ast. Εφόσον δεν βρεθούν αναζητεί τύπο ’bool’ ή ’file’, αλλιώς επιστρέφει τύπο ’string’. - is_date Ελέγχει αν το κείμενο περιγράφει ημερομηνία με την βοήθεια της έτοιμης συνάρτησης parse του πακέτου dateutil.parser. - find_quoted_text Εντοπίζει κείμενο σε εισαγωγικά με την βοήθεια regular expressions. - is_array Εντοπίζει κείμενο εντός αγκυλών ([]) με την βοήθεια regular expressions. - is_quoted_text Ελέγχει αν πρόκειται για κείμενο εντός εισαγωγικών με την βοήθεια regular expres- sions. - is_data_type Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 74

Εικόνα 4.5: Αντιστοιχία γνωστών φράσεων με status codes

Εικόνα 4.6: Η αντιστοιχία ρημάτων αγγλικής γλώσσας με HTTP ρήματα/op- erations [23][21]

Ελέγχει αν το δοσμένο string αποτελεί τύπο δεδομένων με την βοήθεια των type_of_value, is_quoted_text, is_array, is_date. - is_password Ελέγχει αν το δοσμένο string αποτελείται μόνο από αστερίσκους (*), οπότε και πρόκειται για κωδικό Τεχνικές που εφαρμόζονται στον Formatter Ο Formatter δέχεται ως είσοδο το μοντέλο τεχνικών χαρακτηριστικών του NLP En- gine. Ο Formatter γνωρίζει και αυτός όλες τις συμβάσεις και τις σχεδιαστικές αρχές του συστήματος και τις αξιοποιεί. Αποτελείται από μία βασική συνάρτηση την gener- ate_swagger. Στόχος της συνάρτησης είναι η μετατροπή του τεχνικού μοντέλου σε μοντέλο swagger. Η σειρά των βημάτων εντός της generate_swagger έχει σημασία. Στην συνέχεια περιγράφονται οι συναρτήσεις του Formatter. generate_swagger Η συνάρτηση μετατρέπει το τεχνικό μοντέλο του NLP Engine σε valid OpenAPI Specifi- cation. Στην συνάρτηση τα resources εξετάζονται πέντε φορές: 1. Την πρώτη φορά αναζητούνται τα paths, τα queries, τα bodies των HTTP αιτημάτων και τα descriptions των operation. Προκειμένου αυτό να επιτευχθεί, τα operations του resource εξετάζονται έξι φορές. Τις πρώτες δύο ορίζονται οι παράμετροι των path για τα operation GET, PUT, DELETE. Σε αυτό συνεισφέρει και η συνάρτηση constr_path. Στην συνέχεια, εφ’ όσον έχουν εντοπισθεί τα paths, τα operations εξετάζονται άλλες δύο φορές ώστε να οριστούν τα query, με την βοήθεια της con- str_query. Έπειτα, ορίζονται τα bodies των request και τα μοντέλα αυτών με την Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 75

Εικόνα 4.7: Λίστες φράσεων μεγίστων και ελαχίστων

βοήθεια της constr_schema. Τέλος ορίζεται το description του σεναρίου, εφ’ όσον υπάρχει. 2. Πλέον έχουμε τις παραμέτρους των path, οπότε μπορούμε να φτιάξουμε τα τελικά path επιλύοντας τις ιεραρχίες. Έτσι στο δεύτερο πέρασμα και με βάση τις όποιες ιεραρχίες των resources εντοπίστηκαν στο NLP, κατασκευάζουμε τα νέα path, προσέχοντας τις path παραμέτρους που κληρονομούνται από την ιεραρχία. Θεωρητικά υποστηρίζεται άπειρη ιεραρχία, εφόσον πάντα υπάρχει ένα ’root re- source’. Στιγμιότυπο του μοντέλου που χρησιμοποιείται για την επίλυση των ιεραρχιών φαίνεται στην Εικόνα 4.8. 3. Στο τρίτο πέρασμα κατασκευάζονται οι HTTP απαντήσεις. Οι παράμετροι και τα HATEOAS links οργανώνονται ανά status code, όπως αυτά εντοπίσθηκαν στο NLP Engine. Για τις παραμέτρους ισχύει ό,τι και για τις body παραμέτρους των HTTP αιτημάτων. Τα HATEOAS links, επειδή στην παρούσα έκδοση του OpenAPI Speci- fication δεν υποστηρίζονται με φυσικό τρόπο, προστίθενται ως vendor extension με πρόθεμα ’x-’ 4. Την τέταρτη φορά εντοπίζονται ορίζονται οι ρόλοι και τα δικαιώματα αυτών με βάση το oauth2. 5. Τέλος, αφαιρούνται από την τυποποίηση άδεια μοντέλα και ενημερώνονται όλα τα paths στο specification με τις ιεραρχίες τους (άρα και τα hateoas links). Στο τέλος της παραπάνω διαδικασίας έχει ολοκληρωθεί το paths_object του OpenAPI Specification. Επιπλέον όλες οι παράμετροι των HTTP αιτημάτων και των HTTP απαντήσεων οργανώνονται αυτόματα σε μοντέλα (HTTP μοντέλα), τα οποία με τη σειρά τους προστίθενται στο definitions_object του OpenAPI Specification. Τα μοντέλα των HTTP απαντήσεων είναι διαφορετικά για κάθε status code. Έτσι ενώ υπάρχει ένα μοντέλο για κάθε HTTP αίτημα, δεν συμβαίνει το ίδιο και για μία HTTP απάντηση. Περαιτέρω, αν έχουν ορισθεί μοντέλα κατά την διαδικασία συγγραφής της Gherkin, αυτά επίσης προστίθενται στο definitions_object και καθίστανται προσβάσιμα από τα HTTP μοντέλα με σύνδεση ’ref’ όπως ορίζει το OpenAPI Specification. Η ίδια σύνδεση χρησιμοποιείται για την παραπομπή των HTTP μοντέλων από το paths_object. Τέλος οι ρόλοι και τα δικαιώματα αυτών ορίζονται στο security_definitions_object. - flatten Μετατρέπει πίνακες πινάκων (list σε python) σε μονοδιάστατους πίνακες. - constr_path Ορίζει τις ιδιότητες μίας path παραμέτρου - constr_query Ορίζει τις ιδιότητες μίας query παραμέτρου Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 76

Εικόνα 4.8: Gherkin2OAS: Εσωτερικό μοντέλο που χρησιμοποιείται στον formatter για επίλυση ιεραρχιών

- constr_schema Ορίζει τις ιδιότητες μίας schema παραμέτρου Αναλυτικά παραδείγμα των object του OpenAPI Specification, φαίνονται στο Κεφάλαιο 5 και στο Παράρτημα.

4.2.3 Γράφοι καταστάσεων

Το σύστημα πλαισιώνει γραφικά ένας σχεδιαστής γράφων. Ο τελευταίος δέχεται ως είσοδο τα μοντέλα γράφων του NLP Engine και τα αναπαριστά με γράφους σε αρχεία pdf. Υπάρχουν τρεις τύποι γράφων • Ο γράφος μετάβασης καταστάσεων σε επίπεδο πόρων Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 77

• Ο γράφος μεταβάσης καταστάσεων σε επίπεδο εφαρμογής (application state), σε user friendly μορφή • Ο γράφος μεταβάσης καταστάσεων σε επίπεδο εφαρμογής, σε τεχνική μορφή Ο πρώτος γράφος φαίνεται στην Εικόνα 4.9. Κάθε κορυφή του γράφου αντιστοιχεί σε ένα resource, ενώ οι ακμές αντιστοιχούν σε δυνατές μεταβάσεις με http αιτήματα από έναν πόρο σε έναν άλλον.

Εικόνα 4.9: Γράφος μετάβασης καταστάσεων σε επίπεδο πόρων

Οι δύο άλλοι γράφοι φαίνονται στις Εικόνες 4.10 και 4.11. Οι γράφοι μετάβασης κατάστασης εφαρμογής έχουν ώς κορυφές καταστάσεις εφαρμογής και ως ακμές http αιτήματα. Στις κορυφές εμφανίζεται το όνομα του πόρου, το όνομα του σεναρίου και το sta- tus code. Παρατηρούμε ότι σε αυτούς τους γράφους κάποιες ακμές είναι χρωματισμένες με κόκκινο. Οι κόκκινες ακμές μας δείχνουν ότι το Gherkin2OAS εντόπισε αμφιλεγόμενες μεταβάσεις. Δηλαδή δύο ίδιες μεταβάσεις (ίδιο http αίτημα) με κοινή προέλευση προς δύο διαφορετικές καταστάσεις με ίδιο status code. Αν πάρουμε την αυστηρή θεώρηση ότι το interface του συστήματος είναι μόνο το HTTP, το σύστημα θα είναι REST όταν σε κάθε status code αντιστοιχεί ένα και μόνο ένα application state. Διότι αν αντιστοιχούσαν δύο ή παραπάνω application state σε ένα status code, τότε πως θα επέλεγε ο client ανάμεσα σε Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 78

δύο; Ο Roy Fielding μας λέει ότι το application state διαφημίζεται μόνο μέσω των hyper- media. Αν λοιπόν έχουμε ένα http αίτημα, άρα ένα hypermedia, τότε αυτό δεν μπορεί να διακριθεί από ένα άλλο χωρίς επιπλέον πληροφορίες. Θα μπορούσαμε να παραθέσουμε επιπλέον πληροφορίες, δίπλα στο hypermedia, αλλά τότε θα δημιουργούσαμε ένα υπό πρωτόκολλο μέσα στο HTTP. Έτσι θα παραβιάζαμε τον περιορισμό Uniform Interface του REST. Αν πάρουμε μία λιγότερο αυστηρή, αλλά και την επικρατέστερη σήμερα θεώρηση, ότι δηλαδή στην απόφαση μετάβασης συνεισφέρει και το body του HTTP αιτήματος, τότε το σύστημα είναι γενικώς REST. Σε αυτή την περίπτωση οι κόκκινες ακμές επισημαίνουν στο μηχανικό του εξυπηρετητή (server) ότι πρέπει με βάση κάποιες, μη ξεκάθαρες για το API, πληροφορίες, να στέλνεται στον πελάτη η κατάλληλη αναπαράσταση πόρου (ανάμεσα στις δύο). Επίσης επισημαίνουν στον μηχανικό του συνολικού συστήματος ότι πρέπει να εξηγήσει με περιγραφές του API (άρα με descriptions στα Gherkin σενάρια) πώς θα αντιμετωπίζει ο πελάτης (client) τις φαινομενικά όμοιες καταστάσεις. Αν κρίνει ότι η επεξήγηση είναι αρκετά περίπλοκη, τότε ενδεχομένως πρέπει να αλλάξει τον σχεδιασμό του συστήματος προσθέτοντας νέους πόρους (Ενότητα 5.3.2). Με βάση τους γράφους, ο έλεγχος του συστήματος ως προς το πόσο REST είναι έχει ως εξής: 1. Μελέτη γράφου μετάβασης καταστάσεων σε επίπεδο πόρων. Προκειμένου το σύστημα να είναι REST, αναγκαία συνθήκη είναι να συνδέεται κάθε ζευγάρι κορυφών με ένα κατευθυνόμενο μονοπάτι. Αν αυτό δεν ισχύει, το σύστημα δεν είναι REST. 2. Μελέτη του γράφου μεταβάσης καταστάσεων σε επίπεδο εφαρμογής. Αν εμφανίζονται κόκκινες ακμές, το σύστημα μπορεί να μην είναι REST. Στην Ενότητα 5.3.2 θα δούμε πώς επιλύεται αυτό το πρόβλημα. 3. Μελέτη του γράφου μεταβάσης καταστάσεων σε επίπεδο εφαρμογής. Αν όλες οι ακμές είναι χρωματισμένες μαύρες, το σύστημα είναι πιθανόν REST. Για να είναι REST πρέπει και εδώ να υπάρχει ένα κατευθυνόμενο μονοπάτι από κάθε κατάσταση εφαρμογής σε κάθε άλλη. Αν αυτό ισχύει, τότε το σύστημα είναι REST. Η παραπάνω διαδικασία μπορεί να εκτελείται όσες φορές θέλουμε, για όσα νέα resources βάζουμε στο σύστημά μας.

4.2.4 Gherkin2OAS Data Flows

Το Gherkin2OAS έχει δύο διαφορετικά data flow. Το βασικό φαίνεται στην Εικόνα 4.12. Πρόκειται για την κανονική λειτουργία, οπότε και δέχεται ως είσοδο ένα σύνολο από resource files. Εναλλακτικά, υπάρχει και η δυνατότητα εκτέλεσης με την χρήση ενός προηγούμενου τεχνικού μοντέλου, εξαγόμενου από το NLP Engine. Το data flow της εναλλακτικής λειτουργίας φαίνεται στην Εικόνα 4.13.

4.2.5 Gherkin2OAS Production Environment

Στην ενότητα αυτή θα παρουσιάσουμε την διαδικασία ανάπτυξης RESTful Web APIs με την Gherkin, το Gherkin2OAS και το OpenApi Specification. Επισημαίνουμε ότι η μόνη προϋπόθεση εκτέλεσης του Gherkin2OAS είναι η ύπαρξη python έκδοσης 3+ στο λειτουργικό. Το Gherkin2OAS μπορεί να εκτελεστεί σε οποιοδήποτε από τα τρία γνωστά λειτουργικά (Windows, Linux, MAC OS X). Η διαδικασία ξεκινάει με την καταγραφή των απαιτήσεων του API σε Gherkin γλώσσα με βάση το Gherkin Specifications Document. Μπορούν να γραφούν όσα resources επιθυμεί Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 79

Εικόνα 4.10: Ο γράφος μεταβάσης καταστάσεων σε επίπεδο εφαρμογής, σε user friendly μορφή

ο μηχανικός. Στο τέλος της διαδικασίας, υπάρχει ένας φάκελος στο λειτουργικό που περιέχει τα resources (εικόνα 4.15). Στην συνέχεια ο μηχανικός πρέπει να εκτελέσει το Gherkin2OAS. H εκτέλεση ξεκινάει από το τερματικό. Σημειώνεται ότι έχει σχεδιαστεί και μία αρχική γραφική διεπαφή, αλλά η ανάπτυξή της σταμάτησε διότι δεν είχε ξεκάθαρο ρόλο. Το μοναδικό παράθυρο της διεπαφής φαίνεται στην Εικόνα 4.14. Έτσι πρώτα πρέπει να εκκινηθεί ένα τερματικό. Έπειτα, μέσω του τερματικού πρέπει να γίνει πλοήγηση στον φάκελο που υπάρχει το Gherkin2OAS. Στην συνέχεια, δίνεται η αντίστοιχη εντολή εκκίνησης, όπως φαίνεται παρακάτω:

Παράδειγμα 4.19: Εκκίνηση Gherkin2OAS - τερματικό python main.py −f −m −fg

Οι επιλογες ’-f’ και ’-m’ είναι προαιρετικές αλλά μόνο μία μπορεί να χρησιμοποιηθεί. Η επιλογή -fg σημαίνει ’fix graph’ και δεν παίρνει είσοδο αλλά είναι boolean. Η επιλογή ’-f’ αφορά τον φάκελο με τα resource files. Η επιλογή ’-m’ αφορά ένα αρχείο μοντέλου. Όταν το Gherkin2OAS εκτελείται, παράγει ένα αρχείο ’nlp_model.json’. Το αρχείο αυτό, περιέχει το τεχνικό μοντέλο που προκύπτει από την εφαρμογή μηχανισμών NLP στα resource files. Επειδή η εφαρμογή των μηχανισμών αυτών (δηλαδή το NLP En- gine) καθυστερεί, δίνεται η δυνατότητα να φορτώνονται έτοιμα μοντέλα από προηγούμενες εκτελέσεις, τα οποία είναι αποθηκευμένα σε αρχεία τύπου json και έχουν παραχθεί από το Gherkin2OAS. Ένα τέτοιο αρχείο μπορεί να φορτωθεί μέσω της επιλογής -m. Όταν ενεργοποιείται η επιλογή -fg, ο χρήστης θα παροτρυνθεί να διορθώσει αμφιλεγόμενες Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 80

Εικόνα 4.11: Ο γράφος μεταβάσης καταστάσεων σε επίπεδο εφαρμογής, σε τεχνική μορφή

μεταβάσεις καταστάσεων στους γράφους, χειροκίνητα. Τέλος πρέπει να συμπληρωθεί και το αρχείο ’spec_config.ini’. Το αρχείο αυτό περιέχει τις γενικές πληροφορίες για το API. Από το αρχείο απαραίτητα πρέπει να συμπληρωθούν οι μεταβλητές ’title’, ’version’, ’basePath’ και ’host’. Επισημαίνεται ότι το basePath ξεκινάει πάντα με /. Παράδειγμα του ’spec_config.ini’ φαίνεται στην Εικόνα 4.16. Με το πέρας της εκτέλεσης δημιουργούνται 6 αρχεία στον φάκελο ’output_files’. Τα ’swagger.json’, ’swagger.yaml’, ’nlp_model.json’, ’resource_state_graph.gv.pdf’, ’state_graph.gv.pdf’ και ’http_state_graph.gv.pdf’ (Εικόνα 4.17). Τα ’swagger.json’ και ’swagger.yaml’ περιέχουν το OpenAPI Specification σε json και yaml μορφή αντίστοιχα. Το ’nlp_model.json’ περιέχει το μοντέλο τεχνικών χαρακτηριστικών του NLP Engine. Τα pdf αρχεία απεικονίζουν τους γράφους καταστάσεων. Οι γράφοι μπορούν να αξιοποιηθούν από τους μηχανικούς για περαιτέρω συζήτηση με τον πελάτη αλλά και για βελτίωση του συστήματος. Μέσω αυτών μπορεί να επιβεβαιωθεί με οπτικό τρόπο, αν είναι σωστό το επιχειρησιακό πρωτόκολλο, όπως και αν το σύστημα είναι RESTful. Εφόσον έχει επιβεβαιωθεί το validity του swagger αρχείου από το Gherkin2OAS, στην Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 81

Εικόνα 4.12: Gherkin2OAS: Data Flow

συνέχεια μπορεί να παραχθεί ο κώδικας του συστήματος και της εφαρμογής αλλά και το documentation. Ο κλασσικός τρόπος για να γίνει αυτό είναι με το Swagger Code Genera- tor1. Αφού γραφεί τουλάχιστον ο κώδικας του συστήματος, το API μπορεί να δοκιμαστεί. Οι δοκιμές μπορούν να γίνουν είτε από εργαλεία του swagger, όπως ο editor ή το Swag- ger UI, είτε από πληθώρα άλλων γνωστών εργαλείων στην αγορά. Επισημαίνουμε εδώ ότι δοκιμές μπορούν να γίνουν μέχρι και για ένα μόνο resource file. Εξ’ άλλου με βάση το BDD και το Agile manifesto γενικότερα, δεν προτείνεται η ανάπτυξη ολόκληρου του συστήματος εξ’ αρχής. Στόχος είναι να γράφονται μόνο τα απαραίτητα resource files, να παράγεται μόνο ο απαραίτητος κώδικας και να εκτελούνται μόνο τα απαραίτητα test. Αφού ολοκληρωθεί η διαδικασία των δοκιμών, μπορούν να γίνουν νέες συζητήσεις με τους πελάτες με βάση τα αποτελέσματα. Επίσης, αν έχει γραφεί μέρος της εφαρμογής, μπορεί να επιδειχθεί και η λειτουργία του συστήματος.

1https://github.com/swagger-api/swagger-codegen Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 82

Εικόνα 4.13: Gherkin2OAS: Alternative Data Flow

Εικόνα 4.14: Gherkin2OAS: GUI

Εικόνα 4.15: Φάκελος με αρχεία resource Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 83

Εικόνα 4.16: Παράδειγμα αρχείου spec_config.ini

Εικόνα 4.17: Αρχεία εξόδου εκτέλεσης Gherkin2OAS Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 84

Εικόνα 4.18: Εποπτεία του API με τον swagger editor - Editor Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 85

Εικόνα 4.19: Εποπτεία του API με τον swagger editor - API UI Κεφάλαιο 4. Μεθοδολογία & Υλοποίηση συστήματος 86

Εικόνα 4.20: Δοκιμή του API με τον swagger editor 87 Κεφάλαιο 5

Πειράματα & Αποτελέσματα

Στο κεφάλαιο αυτό παρουσιάζουμε παραδείγματα χρήσης του RDD, και τα Open API Spec- ification που εξήχθησαν από αυτά. Πριν όμως δούμε τα παραδείγματα, κρίνεται σκόπιμο να σχολιαστεί η δυνατότητα αξιολόγησης του συστήματος.

5.1 Ο μηχανισμός διασφάλισης της αξιοπιστίας του συστήματος

Διακρίνονται οι εξής μετρικές αξιολόγησης του συστήματος: • Διασφάλιση της επιτυχούς εκτέλεσης του κώδικα, λόγω επεξεργασίας φυσικής γλώσσας • Διασφάλιση της εξαγωγής valid OpenAPI Specification, λόγω επεξεργασίας φυσικής γλώσσας • Ευχρηστία του RDD • Εκπλήρωση απαιτήσεων συστήματος (ενότητα 3.2.3) Η τήρηση των κανόνων του RDD διασφαλίζει πάντα την επιτυχή εκτέλεση του κώδικα και την εξαγωγή valid OpenAPI Specification. Αυτό θα διαπιστωθεί παρακάτω, όπου θα εξεταστούν με παραδείγματα όλα χαρακτηριστικά του συστήματος. Η μη τήρηση των κανόνων του RDD θα οδηγεί πάντα σε invalid OpenAPI Specification. Επιπρόσθετα, το σύστημα δεν μπορεί να διασφαλίσει την επιτυχή εκτέλεση του κώδικα, στην περίπτωση που στο ελεύθερο κείμενο εισάγονται εσκεμμένα τυχαίοι χαρακτήρες, λέξεις και προτάσεις. Η αντιμετώπιση τέτοιων περιπτώσεων θα αναιρούσε το κέρδος της μειωμένης πολυπλκότητας του κώδικα, λόγω RDD. Σε κάθε περίπτωση τέτοιες περιπτώσεις δεν θα έπρεπε να ενδιαφέρουν, δεδομένου ότι το σύστημα σχεδιάστηκε για παραγωγή λογισμικού. Επομένως μη εκτέλεση του κώδικα, δεν θα σήμαινε παραδείγματος χάρη απώλεια προσωπικών δεδομένων, παραβίαση συστήματος κ.λ.π.. Εάν ο κώδικας δεν εκτελεστεί, σημαίνει ότι σίγουρα δεν ακολουθούνται οι κανόνες του RDD. Άρα το πρόβλημα διορθώνεται γρήγορα με συμμόρφωση στους κανόνες. Το ίδιο ισχύει και για το validity του OpenAPI Specification. Η πλήρης αναξιοπιστία του συστήματος όταν δεν ακολουθείται πιστά η μεθοδολογία RDD, είναι σκόπιμη. Όπως ένας compiler γλώσσας προγραμματισμού δεν εξασφαλίζει ποτέ το επιτυχές compilation στην περίπτωση μη τήρησης του συντακτικού, έτσι και το Gherkin2OAS δεν μπορεί να διασφαλίσει την επιτυχή εξαγωγή OpenAPI Specification σε περίπτωση μη τήρησης του RDD. Επιπρόσθετα, ο compiler προσπαθεί να συμβάλλει στην συγγραφή σωστού κώδικα με μηνύματα επισήμανσης λαθών. Το Gherkin2OAS περιέχει μερικά τέτοια μηνύματα, όπου κατέστη εφικτό. Παραδείγματος χάρη τα μηνύματα • ’Warning found duplicate path parameters:...’ Κεφάλαιο 5. Πειράματα & Αποτελέσματα 88

• ’Warning, could not find a status code in the phrase...’ • ’Incorrect table format’ • ’A unique post operation inside a resource file must ALWAYS specify at least one body parameter’ • ’Warning, parameter was detected as linking between the resources but was not found in any detected paths. Was it mentioned in any scenario?’ • ’No ’operation name’ operation found in resource file ’resource file name’ but such a hateoas link was described in resource file ’resource file name” • ’File type in response is bugged, see https://github.com/OAI/OpenAPI- Specification/issues/260’ αποτελούν τέτοιου είδους μηνύματα. Έτσι στην πραγματικότητα ο μηχανικός ”προγραμματίζει” το OpenAPI Specification. Άρα ο μηχανισμός διασφάλισης αξιοπιστίας του συστήματος είναι το Gherkin συντακτικό που ορίζει το RDD. Με βάση αυτή την συλλογιστική, η μετρική αξιολόγησης του συστήματος με μεγαλύτερη βαρύτητα, είναι αυτή της ευχρηστίας. Η ευχρηστία του συστήματος μπορεί να διαπιστωθεί με δύο μεθόδους: 1. Με την δοκιμή του συστήματος σε πραγματικό περιβάλλον παραγωγής λογισμικού 2. Με τον έλεγχο συμμόρφωσης σε γνωστές πρακτικές, οι οποίες έχουν αποδώσει αποτελέσματα Η πρώτη μεθοδολογία δεν κατέστη εφικτή στα πλαίσια της διπλωματικής. Αντίθετα, η δεύτερη μεθοδολογία συνδέεται άμεσα με τις απαιτήσεις του συστήματος. Η εκπλήρωση των απαιτήσεων του συστήματος (Ενότητα 3.2.3) κρίνεται επιτυχής ως εξής: • Το σύστημα είναι REST-aware. Το Κεφάλαιο 4 επιβεβαιώνει αυτόν τον ισχυρισμό. • Το σύστημα είναι Agile-friendly, διότι οι απαιτήσεις περιγράφονται με μορφή User Story. Επίσης δεν απαιτείται η περιγραφή όλων των resources εξ’ αρχής. • Το σύστημα είναι OAS-aware, διότι υποστηρίζεται το path object, όλα τα είδη def- inition, όλοι οι μη τεχνικοί (όπως byte) τύποι δεδομένων, όλα τα είδη παραμέτρων, όλες οι θέσεις παραμέτρων (εκτός του header που αφορά τεχνική περιγραφή), ο μηχανισμός παραπομπής μοντέλων (’$ref’), required παράμετροι και στο path ob- ject και στα μοντέλα, διαφορετικά status code στις HTTP απαντήσεις και τέλος οι πληροφορίες του API με το αρχείο ’spec_config.ini’. • Η εκτέλεση γίνεται σε λογικά γρήγορο χρόνο (βλ. 5.2). • Οι απαιτήσεις που καταγράφονται σε Gherkin είναι μόνο τύπου λειτουργικες • Το σύστημα λαμβάνει υπ΄ όψιν ότι ο χρήστης του API είναι και ο μηχανικός λογισμικού, με το να είναι REST-aware και OAS-aware (σχόλιο: η υποστήριξη path hierarchies επίσης συνεισφέρει στην εκπλήρωση αυτής της απαίτησης, μιας και καθιστά τα path ενστικτώδη (intuitive)) • Η ανάπτυξη του συστήματος κατέστη εφικτή χάρη στην κατανόηση του REST, των δυνατοτήτων του NLP, των χαρακτηριστικών του OAS και τον σχεδιασμό της μεθοδολογίας RDD. Με βάση τα παραπάνω, το σύστημα ακολουθεί γνωστές πρακτικές. Κεφάλαιο 5. Πειράματα & Αποτελέσματα 89

Αναφέρουμε τέλος ότι το OpenAPI Specification που δημιουργείται από το Gherkin2OAS, ελέγχεται ως valid με τον swagger-spec-validator 2.0.31. Αν είναι valid, τυπώνεται σχετικό μήνυμα.

5.2 Ταχύτητα εκτέλεσης και POS Tagging

Η ταχύτητα εκτέλεσης του Gherkin2OAS εξαρτάται μόνο από την ταχύτητα του POS Tagging. Όλες οι άλλες διαδικασίες είναι αμελητέου χρόνου. Ο χρόνος του POS Tag- ging εξαρτάται κατ’ αρχήν από το πόσες φορές καλείται ως διαδικασία. Εξαρτάται όμως και από τον tagger. Έτσι αν πάρουμε ώς δεδομένο τον αριθμό κλήσεων, βελτίωση θα αποτελούσε η επιλογή γρήγορου tagger. Ταυτόχρονα όμως, πρόβλημα αποτελεί το accu- racy του tagger. Στην δική μας περίπτωση μας ενδιαφέρει μόνο ο εντοπισμός ουσιαστικών και ρημάτων. Δεδομένου ότι οι προτάσεις των σεναρίων της Gherkin είναι μικρές (έως συνθηματικές), θα ανέμενε κανείς ο οποιοσδήποτε tagger θα είχε 100% accuracy ως προς τον εντοπισμό τους. Στην πραγματικότητα όμως ενώ ο tagger του nltk είναι εξαιρετικά γρήγορος, δεν καταφέρνει πάντα να εντοπίσει τα ρήματα και τα ουσιαστικά. Αντίθετα άλλοι tagger, όπως ο Stanford tagger ή ο Senna Tagger, καταφέρνουν να τα εντοπίσουν, αλλά σε μεγαλύτερο χρόνο. Προφανώς επιλέγεται η χρήση πάντα αξιόπιστων tagger έναντι αναξιόπιστων γρήγορων. Δεδομένου ότι τα σενάρια είναι παρόμοιας μορφής και μεγέθους, μπορούν να αξιοποιηθούν για την μέτρηση μέσου χρόνου εκτέλεσης. Αυτός είναι ο μόνος τρόπος να μελετήσουμε τις επιδόσεις του συστήματος αφού δεν υπάρχουν μεγάλα dataset γραμμένα με RDD. Ύστερα από εκτελέσεις στα σενάρια των παρακάτω παραδειγμάτων, προέκυψε ότι ο μέσος χρόνος επεξεργασίας σεναρίου είναι 1.4 δευτερόλεπτα με τον Stanford ή τον Senna Tag- ger. Σε προσπάθεια αυτός ο χρόνος να βελτιωθεί, βρέθηκε ο εξής POS Tagger: https: //explosion.ai/blog/part-of-speech-pos-tagger-in-python. Ο tagger χρησιμοποιεί Averaged Perceptron2 για τον εντοπισμό των tags. Ο tagger αυτός είχε 0.9 δευτερόλεπτα μέσο χρόνο επεξεργασίας σεναρίου. Δεδομένου ότι και αυτός εντοπίζει με 100% accuracy τα ρήματα και τα ουσιαστικά σε μικρές προτάσεις, επιλέχθηκε έναντι των άλλων δύο.

1https://pypi.python.org/pypi/swagger-spec-validator 2https://en.wikipedia.org/wiki/Perceptron Κεφάλαιο 5. Πειράματα & Αποτελέσματα 90

5.3 Αναλυτικά Παραδείγματα, Πειράματα και αποτελέσματα

Στην ενότητα αυτή θα εξετάσουμε αναλυτικά και βήμα βήμα την συγγραφή 2 web εφαρμογών, με το σύστημα που σχεδιάστηκε. Τα τελικά valid OpenAPI Specifications των web εφαρμογών, βρίσκονται στο παράρτημα. Για λόγους αναγνωσιμότητας, επιλέγουμε για την παρουσίαση των παραδειγμάτων την γραφική αναπαράσταση του API από τον swagger editor, έναντι του specification.

5.3.1 Mytop10 API

Η πρώτη web εφαρμογή έχει σχεδιαστεί ως πλαίσιο εργασίας από μεταπτυχιακούς φοιτητές. Η περιγραφή της εφαρμογής βρίσκεται στην διεύθυνση https://github.com/ SteliosArakliotis/ErgasiaSaaS. ”Πρόκειται για μια εφαρμογή με κοινωνικό χαρακτήρα όπου οι χρήστες μπορούν να δημοσιεύουν λίστες με τις 10 αγαπημένες τους ταινίες, σειρές και τραγούδια, είτε συγκεκριμένης κατηγορίας είτε γενικά. Σκοπός της εφαρμογής είναι να καθιερωθεί ως ένας τρόπος έκφρασης του χρήστη και ανταλλαγής κριτικών απόψεων. Πρόκειται για μια προσβάσιμη εφαρμογή SaaS όπου θελουμε να ξεχωρίζει για το user friendly χαρακτήρα της.” Στο repository αυτό υπάρχει αρχείο περιγραφής του API της εφαρμογής (https://github. com/SteliosArakliotis/ErgasiaSaaS/blob/master/specifications/mytop10_api.md). Με βάση αυτή την περιγραφή γράφτηκαν τα αντίστοιχα, και κατά RDD, αρχεία. Επισημαίνεται ότι το API δεν είναι REST, διότι δεν χρησιμοποιεί HATEOAS. Καθώς μελετούμε το API, αντιμετωπίζουμε την περιγραφόμενη του λειτουργία ως αποτέλεσμα επικοινωνίας με έναν πελάτη. Έτσι αφού το API μελετήθηκε, αποφασίστηκε να δημιουργηθεί αρχικά το resource ’user’. Στην συνέχεια, με βάση την περιγραφή των δημιουργών του API αλλά και προσθήκες, γράφτηκαν τα σενάρια του resource ’user’ ως εξής:

Παράδειγμα 5.1: Mytop10 user resource Feature: user

Scenario: Create user Creates a single user Given that I am authorized as admin When I create a user: | email | `[email protected]` | | username | `Tasos` | | password | ******** | | id | 250 | | date of birth | 04/05/1992 | | sex | `male` | | location | `Thessaloniki` | | photo | `http://photo.com/myphoto` | | status | `online` | | trophy | `name` | Then I should see a message "Successfull new account"

Scenario: Attempt to create user while not being authorized # Given that I am not authorized to create users Κεφάλαιο 5. Πειράματα & Αποτελέσματα 91

When I attempt to create, view, delete or update the user Then I should see a message "You are unauthorized to make this request."

Scenario: View user`s details Shows details of single user When I request a user by his id Then I should see his username | username | `Tasos` |

Scenario: User does not exist # Given that the user does not exist When I request, update or delete a user by his id Then I should see "User doesn`t exist"

Scenario: Delete user Deletes a single user When I delete a user by his id Then I should see "User deleted successfully"

Scenario: Update user profile Update your user profile When I update a user by his id And I specify the following information | username | `Nick` || | password | ******* | min length of 8 | | date of birth | 09−08−1002 || | sex | `Male` || | location | `Sweden` || | photo | `http://imgur.com/rand_photo` || Then I should see the message "Successfully updated"

Scenario: Check user`s status Returns status about a single user. Valid status requests are `online`, `offline`, `away` and `busy`. The response will be "is " When I request a user by his id And I also request his status | status | `online` | Then I should see | username | "Michalis Pap" | | status | "is online" |

Scenario: Award trophy Give trophy to particular user. When I update a user by it's id And I award a | trophy | `trophytype` | Then I should see the message "Successfully awarded"

Στην συνέχεια εκτελούμε το Gherkin2OAS. Το εξαγόμενο specification είναι valid. Στην Εικόνα 5.1 βλέπουμε τα paths που δημιουργήθηκαν. Το σύστημα σωστά εντόπισε ότι οι user έχουν path παράμετρο id. Επίσης εντόπισε ότι τα GET, PUT, DELETE αναφέρονται σε single resource ενώ το POST σε collection. Συνεχίζοντας, στην Εικόνα 5.2 Κεφάλαιο 5. Πειράματα & Αποτελέσματα 92

Εικόνα 5.1: Mytop10: User resource - paths

Βλέπουμε ότι το Gherkin2OAS, εντόπισε σωστά τέσσερα μοντέλα. Επί αυτών σχολιάζουμε ότι: • Εντοπίστηκε το μοντέλο ’user’, όπως θέλαμε (και σηματοδοτήσαμε) στο σενάριο ’Cre- ate User’ • Εντοπίστηκαν όλοι οι τύποι δεδομένων σωστά, τα αντίστοιχα format τους και τα όριά τους. Έτσι βλέπουμε πληροφορίες όπως ’int32’, ’date’, ’password’ και ’minLength’. • Καταγράφηκε σωστά η σύνδεση μεταξύ του μοντέλου ’user_post_request_body’ και του ’user’ Ως προς το OAuth2 security, βλέπουμε στην Εικόνα 5.3 ότι βρέθηκε ο ρόλος ’admin’ στο σενάριο ’Create User’. Στην Εικόνα 5.4 βλέπουμε το operation GET /user/user_id. Το Gherkin2OAS έχει βρει ότι το operation παίρνει δύο παραμέτρους. Έχει σωστά διαπιστώσει ότι το status param- eter έχει θέση query. Επίσης ότι είναι προαιρετικό (δεν εμφανίζεται σε όλα τα σενάρια που περιγράφουν το ίδιο operation). Περαιτέρω, εντοπίστηκαν σωστά τρία responses και τα μηνύματα αυτών. Η ’default’ σωστά δεν έχει μήνυμα. Παρατηρούμε ακόμη ότι το username στο μοντέλο της ’default’ HTTP απάντησης, έχει δίπλα του ένα αστεράκι (*). Δηλαδή ότι βρέθηκε ως required. Αυτό συνέβη διότι εμφανίζεται σε όλα τις ’default’ HTTP απαντήσεις των σεναρίων που περιγράφουν GET. Τέλος βλέπουμε ότι καταγράφηκαν όλα τα description που περιγράφουν το ίδιο operation. Στην Εικόνα 5.5 βλέπουμε το PUT operation. Εδώ το σημείο σχολιασμού είναι ότι οι request παράμετροι, παρ’ όλο που βρίσκονται σε διαφορετικά σενάρια, οργανώθηκαν σε ένα model. Αυτό συμβαίνει διότι το OpenAPI Specification δεν διακρίνει δύο opera- tion μεταξύ τους, όταν αφορούν το ίδιο path. Ταυτόχρονα δεν προσδιορίστηκαν ονόματα μοντέλων γι’ αυτές, ώστε να διακριθούν σε επίπεδο μοντέλου. Αν όμως εξετάσουμε τον κώδικα του OpenAPI Specification στην Εικόνα 5.6, βλέπουμε ότι καταγράφηκαν δύο διακριτά παραδείγματα, όπως τα περιγράψαμε στα σενάρια. Έτσι ο developer του API μπορεί να αξιοποιήσει και αυτό το χαρακτηριστικό του Gherkin2OAS ώστε να διαπιστώσει διαφορετικά είδη αιτημάτων. Το έργο του μπορεί να βοηθηθεί περαιτέρω με τα διαφορετικά description του operation. Στην προκειμένη περίπτωση αυτά έχουν δοθεί στα σενάρια και καταγράφηκαν. Κεφάλαιο 5. Πειράματα & Αποτελέσματα 93

Εικόνα 5.2: Mytop10: User resource - models

Στις Εικόνες 5.7 και 5.8 βλέπουμε τις περιγραφές των POST και PUT operation. Στο POST παρατηρούμε την καταγραφή του security. Επίσης ότι το model δεν είναι required (σωστό αφού δεν εμφανίζεται σε όλα τα σενάρια που περιγράφουν POST) Στην συνέχεια αποφασίζουμε να δημιουργήσουμε το resource ’list’. Έτσι γράφουμε το feature file του:

Παράδειγμα 5.2: Mytop10 list resource Feature: lists

Background: Lists belong to users Given a user`s id

Scenario: Create new list Create a new single list for a user. When I create a list | id | 30 | | category | `series` | | listname | `top 10 series` | | description | `Best series since 1990` | | date of release | 05/06/2010 | Κεφάλαιο 5. Πειράματα & Αποτελέσματα 94

Εικόνα 5.3: Mytop10: User resource - security

Εικόνα 5.4: Mytop10: User resource - GET user

| tag | `mystery` | Then I could see "List created"

Scenario: Unsuccessfull list creation # Given WW3 When I create a list | id | 30 | | category | `series` | | listname | `top 10 series` | | description | `Best series since 1990` | | date of release | 05/06/2010 | | tag | `mystery` | Then I could see "List not created"

Scenario: Retrieve list Returns a single list of a particular user. When I check a list by it`s id Then I should see it`s name

Scenario: non existing list # Given a list does not exist When I try to view, delete or change a list by it`s id Κεφάλαιο 5. Πειράματα & Αποτελέσματα 95

Εικόνα 5.5: Mytop10: User resource - PUT user

Εικόνα 5.6: Mytop10: User resource - PUT user examples

Then I should see "List doesn`t exist"

Scenario: Anauthorized list viewing and editing When I request or delete a list by it`s id Then I should see "You are unauthorized to make this request."

Scenario: Delete list Delete a single list of a particular user. When I remove a list by it`s id Then I should see "List deleted successfully"

Scenario: View all the lists Returns all lists of a particular user. When I submit an all list retrieval as follows | all | true | Then I should see "OK"

Scenario: Lists don`t exist #Given user has no list When I submit a request for all the user`s lists by specifying | all | true | Κεφάλαιο 5. Πειράματα & Αποτελέσματα 96

Εικόνα 5.7: Mytop10: User resource - DELETE user

Then I should see "There are no lists"

Scenario: Unauthorized to retrieve lists #Given that I don`t have required authorization When I submit a request for all lists | all | true | Then I should see "You are unauthorized to make this request."

Scenario: Change list name: Change a name of a single list. When I change a list by it`s id And I specify a list name as the changed value |listname| `movies`| Then I should see "Listname changed successfully"

Εκτελούμε ξανά το Gherkin2OAS. Στην Εικόνα 5.9 βλέπουμε τα νέα path που δημιουργήθηκαν. Παρατηρούμε ότι οι αλγόριθμοι του formatter έχουν εντοπίσει την ιεραρχία μεταξύ user και list, όπως περιγράφηκε στο Background του list. Έτσι τα path του list κατασκευάστηκαν όπως φαίνεται στην εικόνα. Στις εικόνες 5.10-5.13 φαίνονται οι περιγραφές των νέων operation. Στο POST βλέπουμε ότι εντοπίσθηκαν σωστά τέσσερα status code. Γενικότερα, στα μέχρι τώρα operation τα μηνύματα των status code αντιστοιχίζονται στο σωστό νούμερο. Στην συνέχεια γράφουμε το resource admin:

Παράδειγμα 5.3: Mytop10 admin resource Feature: Manage administrators

Background: Given that I am authorized as system

Scenario: Create a new administrator Creates a new single administrator. When I create a new administrator: | admin name | `ADMIN01` | | admin id | 1 | Κεφάλαιο 5. Πειράματα & Αποτελέσματα 97

Εικόνα 5.8: Mytop10: User resource - POST user

Εικόνα 5.9: Mytop10: List resource - paths

Then I should see "Successfull new admin account"

Scenario: View admin`s details Returns data about a single administrator. When I check an admin by his id Then I should see "OK" And the details of the admin | admin_id | 123 | | username | "Kostas Sotiriou" |

Scenario: Retrieve non existent admin When I check an admin by his id # And there is no such admin Then I should see "Admin doesn`t exist"

Στις Εικόνες 5.14-5.17 βλέπουμε τα νέα entry του OpenAPI Specification. Παρατηρούμε ότι προστέθηκαν δύο νέα path. Επίσης προστέθηκε νέο security definition και Κεφάλαιο 5. Πειράματα & Αποτελέσματα 98

Εικόνα 5.10: Mytop10: List resource - GET

καταχωρήθηκαν τα scopes στα αντίστοιχα operations. Τέλος καταχωρήθηκαν σωστά το μοντέλο του admin, οι τύποι δεδομένων και τα requirements των παραμέτρων. Στην συνέχεια προσθέτουμε το ’rate’ resource:

Παράδειγμα 5.4: Mytop10 rate resource Feature: rate lists

Background: Given a list id

Scenario: Rate a list When I submit a rating for a list: # parameter names as described by product owners | ratio | 7 | | ratio id | 4 | Then I should see "OK, list rated"

Scenario: Rate a non existent list When I submit a rating for a list: | ratio | 7 | | ratio id | 4 | # And the list does not exist Then I should see "List doesn`t exist"

Scenario: Unauthorized list When I submit a rating for a list: | ratio | 7 | | ratio id | 4 | # And I`m not authorized to do so Then I should see "You are unauthorized to make this request."

Στις Εικόνες 5.18-5.18 φαίνονται οι αλλαγές στο OpenAPI Specification. Στην εικόνα με τα paths βλέπουμε ότι το Gherkin2OAS κατάφερε επιτυχώς να εντοπίσει ιεραρχία τριών επιπέδων. Στην εικόνα με το POST operation, το model rating έχει εντοπιστεί και έχει Κεφάλαιο 5. Πειράματα & Αποτελέσματα 99

Εικόνα 5.11: Mytop10: List resource - PUT

καταχωρηθεί σωστά μία φορά (αν και εμφανίζεται τρεις). Επιπλέον βλέπουμε ότι το body είναι σημασμένο ως required, αφού εμφανίστηκε και στα τρία σενάρια της Gherkin. Ακόμη στην εικόνα 5.20 και το μοντέλο ’rating’ εμφανίζεται σωστά ως υποχρεωτική παράμετρος του rate_post_request_body, αφού και αυτό εμφανίστηκε και στα τρία σενάρια. Συνεχίζοντας, αποφασίζουμε να γράψουμε το ’search’ resource, στο οποίο οργανώθηκαν όλες οι αναζητήσεις με query μίας παραμέτρου. Το resource file έχει ως εξής:

Παράδειγμα 5.5: Mytop10 search resource Feature: Search functionality for the system

Scenario: Search for a user Returns data about a single user. When I search for a user And I specify a username Then I should see the user`s short details | email | `[email protected]` | | username | `Tasos` | | id | 250 | | date of birth | 04/05/1992 | And I should see the message "User found"

Scenario: Search for a list Returns data about a single list. When I search for a list And I specify |listname| `movies`| Then I should see the list`s short details | id | 30 | | category | `series` | | description | `Best series since 1990` | And I should see the message "List found"

Scenario: Search for a list by release date Returns data about a single list. Κεφάλαιο 5. Πειράματα & Αποτελέσματα 100

Εικόνα 5.12: Mytop10: List resource - DELETE

When I search for a list And I specify |date of release| 19/02/2017| Then I should see the list`s short details | id | 30 | | category | `series` | | description | `Best series since 1990` | | date of release | 05/06/2010 | And I should see the message "List found"

Scenario: Search for lists with the bigest ratio Returns the lists with the bigest ratio. When I search for a list And I specify | ratio | 5 | | sort | `descending` | Then I should see a sorted by ratio list of lists | sorted list | [`highest ratio listname`, \`medium ratio listname`,`lowest ratio listname`] | maximum 15 items | And I should see "OK"

Scenario: Unauthorized search # Given that I`m unauthorized When I search And I specify for example | ratio | 5 | | sort | `descending` | Then I should see "You are unauthorized to make this request."

Scenario: Search query has no results When I search And I specify for example | ratio | 5 | | sort | `descending` | # And there are no results Then I should see `none found` Κεφάλαιο 5. Πειράματα & Αποτελέσματα 101

Εικόνα 5.13: Mytop10: List resource - POST

Εικόνα 5.14: Mytop10: Admin resource - paths

Στην Εικόνα 5.21 φαίνεται το νέο μοναδικό path που δημιουργήθηκε και η περιγραφή του. Όλες οι query παράμετροι ορθώς ορίστηκαν ως μη required. Οι τύποι δεδομένων εντοπίστηκαν σωστά και εντοπίστηκε και ο τύπος array, τα όρια του και ο εσωτερικός τύπος των δεδομένων του. Τέλος το id είναι required γιατί εμφανίζεται σε όλα τα ’default’ response. (Εδώ τα response codes δεν επιλέχτηκαν απαραίτητα ώστε να έχουν νόημα, αλλά περισσότερο ώστε να αναδειχθούν συνδυασμοί χαρακτηριστικών) Τέλος προσθέτουμε τα resource ’follow list’ και ’comment’:

Παράδειγμα 5.6: Mytop10 search resource Feature: follow list

Background: Given a user`s id

Scenario: Κεφάλαιο 5. Πειράματα & Αποτελέσματα 102

Εικόνα 5.15: Mytop10: Admin resource - security

When I create a new followlist: | users | [1,5,7,12,10] | maximum of 10000 | Then I should see `OK`

Feature: Comment a list

Background: Given a list id

Scenario: Comment list Comment a list of a particular user. When I create a new comment: | comment content | `I like most of your list` | | comment id | 12 | Then I should see "List commented successfully"

Στις Εικόνες 5.22-5.23 εμφανίζονται τα νέα specification. Βλέπουμε και εδώ ότι σωστά εντοπίστηκαν οι ιεραρχίες των path, έως βάθους τρία. Τα body έχουν οριστεί ως required. Επίσης φαίνεται και το μέγεθος του array users στο followlist μοντέλο, όπως και ότι το περιεχόμενό του είναι τύπου ’integer’ με ’int32’ format. Στις εικόνες 5.24-5.25, τα μοντέλα έχουν οριστεί ως required στα requrest_body μοντέλα. Τα παραπάνω resource files περιγράφουν το σύνολο του API. Επισημαίνουμε ότι όλες οι path παράμετροι που εντοπίστηκαν στις ιεραρχίες, κληρονομήθηκαν και στα νέα (χαμηλότερης ιεραρχίας) operations. Σε κάποια σενάρια των resource file, αξιοποιούνται τα comment ως hidden step για καλύτερη περιγραφή του σεναρίου. Στην Εικόνα 5.26 φαίνονται οι εκτελέσεις του Gherkin2OAS για κάθε νέο resource, όπως παρουσιάστηκαν. Βλέπουμε πως ο χρόνος εκτέλεσης αυξάνεται καθώς προσθέτουμε νέα resource. Αν θέλαμε να δοκιμάζουμε το κάθε resource ξεχωριστά, ώστε να έχουμε γρηγορότερους χρόνους εκτέλεσης, θα μπορούσαμε να αφαιρέσουμε τις περιγραφές ιεραρχίας. Έτσι τα resource θα ήταν αυτόνομα από τα υπόλοιπα και θα προσθέταμε τις περιγραφές, όποτε κρίναμε απαραίτητο. Κεφάλαιο 5. Πειράματα & Αποτελέσματα 103

Εικόνα 5.16: Mytop10: Admin resource - GET

5.3.2 Generic e-shop

Στην υπό ενότητα αυτή μελετούμε το OpenAPI Specification ενός γενικού eshop που σχεδιάστηκε στα πλαίσια της διπλωματικής. Προς χάριν παρουσίασης, τα παραδείγματα του Κεφαλαίου 4, βελτιώθηκαν με πιο ρεαλιστικές περιγραφές. Τα resource files βρίσκονται στο Παράρτημα C.2 και δεν παρατίθενται ολόκληρα και εδώ για συντομία. Στην υπό ενότητα αυτή μας ενδιαφέρει να εξετάσουμε την ανάπτυξη του API από μία άλλη σκοπιά και γι αυτό δεν θα μελετήσουμε αναλυτικά όλα τα σενάρια, όπως κάναμε στην προηγούμενη ενότητα. Έτσι εκτελούμε το Gherkin2OAS με όλα τα resource file ως είσοδο. Στις Εικόνες 5.27 και 5.28 βλέπουμε τα paths που δημιουργήθηκαν, όπως θα θέλαμε. Στην Εικόνα 5.29 βλέπουμε το μοντέλο product και τους εντοπισμένους τύπους δεδομένων. Επίσης στην Εικόνα 5.30 βλέπουμε ενδεικτικά την POST HTTP απάντηση του resource ’basket’. Παρατηρούμε ότι καταγράφηκαν σωστά τα arrays, τα examples, τα μέγιστα, οι τύποι δεδομένων και τα requirements. Επίσης βλέπουμε ότι καταγράφηκαν σωστά και τα HATEOAS links. Αν μελετήσει κανείς το OpenAPI Specification στο Παράρτημα C.2, θα διαπιστώσει ότι όλα τα επιθυμητά χαρακτηριστικά έχουν εντοπιστεί. Έτσι εδώ θα εξετάσουμε προσεκτικά τα HATEOAS links καθώς και την REST ανάλυση του API. Στα resource files δεν περιγράφονται HATEOAS links για όλα τα σενάρια. Έτσι το σύστημα δεν είναι εξ’ ορισμού REST. Εμείς θα υποβάλλουμε REST ανάλυση στο υποσύστημα που δημιουργείται από τα σενάρια με HATEOAS links. Για το σκοπό αυτό ο κώδικας του γράφου τροποποιήθηκε σκόπιμα ώστε να αποκρύπτει τα resources χωρίς HATEOAS links. Στο Παράδειγμα 5.7 βλέπουμε τα είκοσι τέσσερα (24) links που εντοπίστηκαν σε έντεκα (11) σενάρια. Όλα τα link εντοπίστηκαν σωστά. Βλέπουμε επίσης ότι έχουν καταχωρηθεί και οι ιεραρχίες των path. Κεφάλαιο 5. Πειράματα & Αποτελέσματα 104

Εικόνα 5.17: Mytop10: Admin resource - POST

Εικόνα 5.18: Mytop10: Rate resource - paths

Παράδειγμα 5.7: Generic eshop: all HATEOAS links And I should be prompted to request a search order_delete_200_response: x−links: − path: /search operation: get

And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order order_post_200_response: x−links: − path: `/order/{order_id}/payment` operation: post − path: `/order/{order_id}` operation: get − path: `/order/{order_id}` operation: delete − path: `/order/{order_id}` operation: put Κεφάλαιο 5. Πειράματα & Αποτελέσματα 105

Εικόνα 5.19: Mytop10: Rate resource - POST

Εικόνα 5.20: Mytop10: Rate resource - required model

And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order order_get_default_response: x−links: − path: `/order/{order_id}/payment` operation: post − path: `/order/{order_id}` operation: get − path: `/order/{order_id}` operation: delete − path: `/order/{order_id}` operation: put

And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order order_put_200_response: x−links: − path: `/order/{order_id}/payment` operation: post Κεφάλαιο 5. Πειράματα & Αποτελέσματα 106

Εικόνα 5.21: Mytop10: Search resource - GET

− path: `/order/{order_id}` operation: get − path: `/order/{order_id}` operation: delete − path: `/order/{order_id}` operation: put

And I should be prompted to add it to the basket product_get_default_response: x−links: − path: /basket operation: post

Then I should be prompted to view the order payment_post_default_response: x−links: − path: `/order/{order_id}` operation: get

And I should be prompted to submit a payment Κεφάλαιο 5. Πειράματα & Αποτελέσματα 107

Εικόνα 5.22: Mytop10: Follow list resource - POST

And I should be prompted to view the order payment_post_400_response: x−links: − path: `/order/{order_id}/payment` operation: post − path: `/order/{order_id}` operation: get

And I have the option to view a product search_get_default_response: x−links: − path: `/product/{product_id}` operation: get

And I should be prompted to create an order And I should have the option to view my basket basket_get_default_response: x−links: − path: /order operation: post − path: `/basket/{basket_id}` operation: get

And I should be prompted to create an order And I should have the option to view my basket basket_put_default_response: x−links: − path: /order operation: post − path: `/basket/{basket_id}` operation: get

And I should be prompted to create an order Κεφάλαιο 5. Πειράματα & Αποτελέσματα 108

Εικόνα 5.23: Mytop10: Comment resource - POST

Εικόνα 5.24: Follow list resource - required model

And I should have the option to view my basket basket_post_default_response: x−links: − path: /order operation: post − path: `/basket/{basket_id}` operation: get

Έχοντας επιβεβαιώσει τον εντοπισμό των link, εξετάζουμε το γράφο με τις μεταβάσεις καταστάσεων σε επίπεδο πόρων. Ο γράφος αυτός έχει την μορφή της Εικόνας 5.31. Παρατηρούμε ότι υπάρχει ένα κατευθυνόμενο μονοπάτι που συνδέει κάθε ζευγάρι κορυφών (υπάρχει κύκλος). Επομένως ικανοποιείται η αναγκαία συνθήκη ώστε το API να είναι REST. Η συνθήκη αυτή όμως δεν είναι ικανή. Συνεχίζουμε την REST ανάλυσή μας, εξετάζοντας των γράφο μετάβασης καταστάσεων σε επίπεδο κατάστασης εφαρμογής. Ο γράφος αυτός φαίνεται στην Εικόνα 5.32. Βλέπουμε ότι υπάρχουν κόκκινες ακμές. Μελετώντας προσεκτικά τις διαδρομές, διαπιστώνουμε ότι όλα τα κόκκινα βέλη καταλήγουν στις καταστάσεις ’view unpaid order (default)’ και ’view Κεφάλαιο 5. Πειράματα & Αποτελέσματα 109

Εικόνα 5.25: Mytop10: Comment resource - required model paid order (default)’. Παρατηρούμε ότι αυτές οι δύο καταστάσεις εφαρμογής έχουν το ίδιο status code (default). Περιγράφηκαν όμως διαφορετικά σενάρια. Αν εξετάσουμε το resource file ’order’, βλέπουμε τις εξής περιγραφές σεναρίων:

Παράδειγμα 5.8: Generic eshop: GET order - διπλή περιγραφή

Scenario: view unpaid order

Given that I have ordered When I request an order by it`s id Then I can view the details of the order | product names | [`Chair`,`Keyboard`,`Dell Laptop`] | | product descriptions | [`Made in Stockholm`,`Mechanical`,`IPS Screen`] | And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Scenario: view paid order

Given that I have ordered When I request an order by it`s id Then I can view the details of the order | product names | [`Chair`,`Keyboard`,`Dell Laptop`] | | product descriptions | [`Made in Stockholm`,`Mechanical`,`IPS Screen`] | And I have the option to review the order

Όταν σχεδιαζόταν το κατάστημα, διαπιστώθηκε ότι στην περίπτωση που μία παραγγελία είχε πληρωθεί, δεν θα μπορούσε να ξανά πληρωθεί, να διαγραφεί ή να ενημερωθεί. Η μόνη δυνατότητα θα ήταν αυτή της προβολής. Αντίθετα στην περίπτωση μη πληρωμένης παραγγελίας, θέλουμε όλες οι παραπάνω ενέργειες να διαφημίζονται στην απάντηση του API. Δεν περιγράψαμε όμως διαφορετικές καταστάσεις για κάθε απάντηση. Στην πραγματικότητα ταυτίσαμε την αλλαγή κατάστασης του πόρου με την αλλαγή στην κατάσταση της εφαρμογής .Έτσι το API θα αγνοεί ποια απάντηση θα διαφημίσει. Από αυτό το σημείο έχουμε δύο επιλογές. Να δώσουμε ένα status code σε μία από τις δύο απαντήσεις ή να δημιουργήσουμε έναν νέο πόρο. Επειδή και τα δύο σενάρια περιγράφουν επιτυχή απάντηση, επιλέγουμε την δημιουργία νέου πόρου. Ο νέος πόρος έχει όνομα ’pending deliveries’ και περιεχόμενο ως εξής:

Παράδειγμα 5.9: Generic eshop: Δημιουργία resource pending deliveries Feature: Check the products pending for delivery Κεφάλαιο 5. Πειράματα & Αποτελέσματα 110

Εικόνα 5.26: Mytop10: Gherkin2OAS execution

Scenario: view delivery # Given that I have ordered When I request a delivery by it`s id Then I can view the details of the order | product names | [`Chair`,`Keyboard`\ ,`Dell Laptop`] | | product descriptions | [`Made in Stockholm`\ ,`Mechanical`,`IPS Screen`] | And I have the option to review the pending deliveries

Εκτελούμε το Gherkin2OAS και δημιουργούμε νέο valid OpenAPI Specification. Έπειτα μελετούμε πάλι τον γράφο μετάβασης καταστάσεων σε επίπεδο πόρων (Εικόνα 5.33). Βλέπουμε ότι εμφανίστηκε μία νέα κορυφή, μη συνδεδεμένη με τον υπόλοιπο γράφο. Αυτό είναι λογικό αφού το νέο σενάριο περιγράφει μόνο ένα HATEOAS link στον εαυτό του. Το ότι το νέο υποσύστημα δεν είναι REST, δεν μας ενδιαφέρει στην παρούσα φάση. Έτσι αυτή την στιγμή μας αρκεί το γεγονός ότι ο υπόλοιπος γράφος έχει κύκλο. Στην συνέχεια μελετούμε τον γράφο μετάβασης καταστάσεων σε επίπεδο εφαρμογής (Εικόνα 5.34). Κεφάλαιο 5. Πειράματα & Αποτελέσματα 111

Εικόνα 5.27: Generic eshop: paths (1/2)

Βλέπουμε ότι η αλλαγή που πραγματοποιήσαμε έλυσε το πρόβλημα με τις καταστάσεις. Αγνοώντας και εδώ την καινούργια κατάσταση, εξετάζουμε αν ο γράφος έχει κύκλο. Διαπιστώνουμε ότι δεν έχει, διότι δεν υπάρχει τρόπος να βρεθούμε στην κατάσταση ’update basket (default)’. Τώρα μπορούμε να συζητήσουμε με τον πελάτη και τους υπόλοιπους μηχανικούς, πώς θα λύσουμε αυτό το πρόβλημα. Έτσι συνεχίζουμε την διαδικασία ανάπτυξης του API. Αν εκτιμούμε ότι μπορούμε να εξηγήσουμε ικανοποιητικά στον client πώς θα επεξεργαστεί τις αμφιλεγόμενες αναπαράστασεις πόρων, τότε μπορούμε να μην προσθέσουμε νέο πόρο. Αντίθετα, μπορούμε να καλέσουμε την λειτουργία ’fix graph’ με την επιλογή -fg στην κλήση τερματικού. Στην περίπτωση αυτή, το σύστημα θα μας προτρέψει να διορθώσουμε τις αμφιλεγόμενες μεταβάσεις όπως φαίνεται στην Εικόνα 5.35. Τα παραπάνω παραδείγματα συνοψίζουν την λειτουργία και τα αποτελέσματα του προτεινόμενου συστήματος. Κεφάλαιο 5. Πειράματα & Αποτελέσματα 112

Εικόνα 5.28: Generic eshop: paths (2/2)

Εικόνα 5.29: Generic eshop: product model Κεφάλαιο 5. Πειράματα & Αποτελέσματα 113

Εικόνα 5.30: Generic eshop: basket post response Κεφάλαιο 5. Πειράματα & Αποτελέσματα 114

Εικόνα 5.31: Generic eshop: Γράφος με μεταβάσεις καταστάσεων σε επίπεδο πόρων Κεφάλαιο 5. Πειράματα & Αποτελέσματα 115

Εικόνα 5.32: Γράφος με μεταβάσεις καταστάσεων σε επίπεδο κατάστασης εφαρμογής Κεφάλαιο 5. Πειράματα & Αποτελέσματα 116

Εικόνα 5.33: Generic eshop: Νέος γράφος με μεταβάσεις καταστάσεων σε επίπεδο πόρων Κεφάλαιο 5. Πειράματα & Αποτελέσματα 117

Εικόνα 5.34: Generic eshop: Νέος γράφος με μεταβάσεις καταστάσεων σε επίπεδο κατάστασης εφαρμογής Κεφάλαιο 5. Πειράματα & Αποτελέσματα 118

Εικόνα 5.35: Generic eshop: Προτροπή διόρθωσης γράφου 119 Κεφάλαιο 6

Συμπεράσματα & Μελλοντικές επεκτάσεις

6.1 Συμπεράσματα

Στην ενότητα αυτή θα εξετάσουμε τα συμπεράσματα που εξήχθησαν από τον σχεδιασμό και την υλοποίηση του συστήματος.

6.1.1 Σχεδιασμού

Το πρώτο συμπέρασμα σχεδιασμού είναι ότι η σύνδεση του REST με την Gherkin είναι εφικτή. Με την σύνδεση αυτή ο Παγκόσμιος Ιστός γίνεται περισσότερο φιλικός τόσο ώς προς τις εφαρμογές όσο και προς τους χρήστες του. Ακολουθώντας την μεθοδολογία RDD, η συγγραφή RESTful Web APIs ταυτίζεται με την επιτυχή σύλληψη του επιχειρησιακού μοντέλου του πελάτη. Επιπλέον, η μεθοδολογία RDD συνάδει με την λογική του BDD. Πιο συγκεκριμένα, τα διάφορα resources μπορούν να σχεδιάζονται αυτόνομα, να μετατρέπονται σε OpenAPI Specification και να δοκιμάζεται άμεσα η λειτουργία του API. Στην συνέχεια μπορεί να υπάρχει περαιτέρω συζήτηση με τον πελάτη και υλοποίηση νέων resource. Έτσι ακολουθείται μία Agile μεθοδολογία ανάπτυξης λογισμικού με συνεχές feedback από τον πελάτη Τέλος, όσον αφορά τις δυνατότητες του σχεδιασμού, επισημαίνουμε το εξής: Σε ένα κείμενο φυσικής γλώσσας, το μειονέκτημα του ασαφούς περιεχομένου μπορεί να μετατραπεί σε πλεονέκτημα. Στην δική μας περίπτωση το κείμενο του Feature και η περιγραφή του, καθώς και το κείμενο του Scenario και η περιγραφή του, αφήνονται ελεύθερα προς χρήση. Τις περιοχές αυτές του Gherkin αρχείου μπορεί έξυπνα να χρησιμοποιήσει ο μηχανικός, ώστε να αποδράσει από τους κανόνες του RDD. Έτσι οι περιγραφές του συστήματος που δεν έχουν άμεση σχέση με το API, αλλά κρίνονται κρίσιμες για την επιτυχή επικοινωνία, βρίσκουν θέση. Ο μηχανικός παροτρύνεται να χρησιμοποιήσει και σχόλια με κρυφά βήματα, οπότε και κρίνει ότι θα βοηθήσουν στον ξεκάθαρο ορισμό του συστήματος.

6.1.2 Υλοποίησης

Το βασικό συμπέρασμα όσον αφορά την υλοποίηση είναι ότι η υλοποίηση εξαρτάται απευθείας από τον σχεδιασμό του RDD. Το οποίο πρακτικά σημαίνει ότι η πολυπλοκότητα του λογισμικού εξαρτάται από το πως περιγράφεται το API σε φυσική γλώσσα. Ο πολυπλοκότητα με την σειρά της συνδέεται με την δυσκολία υλοποίησης, αλλά κυρίως συνδέεται με την αποτελεσματικότητα του συστήματος. Αν ακολουθούσαμε την λογική ”ελεύθερο κείμενο”, τότε θα έπρεπε να γραφεί κώδικας στην θέση των συμβάσεων και των κανόνων του RDD. Έτσι εξηγείται η σύνδεση με Κεφάλαιο 6. Συμπεράσματα & Μελλοντικές επεκτάσεις 120

την πολυπλοκότητα. Όσο περισσότεροι είναι οι κανόνες του RDD, τόσο λιγότερος είναι ο κώδικας. Βέβαια πολλοί RDD κανόνες θα καθιστούσαν δύσκολη την συγγραφή της Gherkin, άρα πρέπει να τηρείται μία ισορροπία. Περαιτέρω, ο αρχικός στόχος ήταν, η υλοποίηση να εντοπίζει όλα τα περιγραφόμενα χαρακτηριστικά. Ο στόχος φάνηκε ιδανικός. Από την άλλη όταν ένα λογισμικό αποτυγχάνει κάποιες φορές τον σκοπό του, τότε η αξία του μειώνεται δραματικά. Είναι προτιμότερο ένα εργαλείο να έχει πάντα αποτελέσματα, από το να έχει κάποιες φορές εξαιρετικά αποτελέσματα και κάποιες φορές καθόλου αποτελέσματα. Με αυτό τον τρόπο συνδέεται η πολυπλοκότητα με την αποτελεσματικότητα. Η λογική του ελεύθερου κειμένου αναπόφευκτα θα οδηγούσε σε περιπτώσεις λάθος ή καθόλου αποτελεσμάτων. Έτσι η υλοποίηση ”προστατεύεται” από το RDD ως εξής: Αν η έξοδος του Gherkin2OAS είναι λανθασμένη ή ελλειπής, τότε αυτό σημαίνει μη τήρηση κανόνων και όχι απρόβλεπτο σενάριο. Κεφάλαιο 6. Συμπεράσματα & Μελλοντικές επεκτάσεις 121

6.2 Μελλοντικές επεκτάσεις

Οι μελλοντικές επεκτάσεις αφορούν τόσο το υπάρχον σύστημα, όσο και νέα χαρακτηριστικά αυτού.

6.2.1 Παράμετροι

Οι παράμετροι είναι ένα από τα βασικότερα στοιχεία ενός RESTful Web API. Mία βελτίωση θα μπορούσε να είναι η ελεύθερη δομή του πίνακα. Αντί η κάθε στήλη/γραμμή να έχει μία ιδιότητα, θα μπορούσε αυτή η ιδιότητα να συμπεραίνεται από το περιεχόμενο των κελιών της. Κάτι τέτοιο θα επέτρεπε και την πρόσθεση περιγραφών στις παραμέτρους (descriptions). Παραδείγματος χάρη, με την τρέχουσα υποστηριζόμενη μορφή πίνακα, η πρόσθεση περιγραφής παραμέτρου, χωρίς η παράμετρος να έχει μέγιστα και ελάχιστα, θα σήμαινε τουλάχιστον μία κενή τρίτη στήλη/γραμμή. Επισημαίνεται ακόμη ότι η περιγραφή των description με εισαγωγικά θα αποτελούσε πρόβλημα σε μία ελεύθερη δομή, διότι τα εισαγωγικά θεωρούνται ως ’string’ data type. Θα μπορούσαν επίσης να προστεθεί υποστήριξη αριθμητικών παραμέτρων τύπου long. Η αναπαράστασή τους όμως πρέπει να γίνει με τέτοιο τρόπο, ώστε η φυσική γλώσσα να μην παίρνει τεχνικά. χαρακτηριστικά. Βελτίωση του συστήματος θα αποτελούσε και η υποστήριξη παραμέτρων κειμένου με κενό ανάμεσά τους. Κάτι τέτοιο θα απαιτούσε πιθανώς NER και Relation Extraction.

6.2.2 Βήμα Given και φυσικότητα γλώσσας Gherkin

Όπως επισημάναμε, το ρήμα Given συγγρούεται σχεδιαστικά με την Stateless αρχή του REST. Αντί αυτό να αποτελέσει πρόβλημα, αξιοποιήθηκε για χαρακτηριστικά που ενδεχομένως δεν θα μπορούσαν να υλοποιηθούν διαφορετικά, τους ρόλους και την ιεραρχία πόρων. Η σχεδιαστική αυτή ευελιξία αναδεικνύει το γεγονός, ότι δεν είναι απαραίτητο όλο το κείμενο της Gherkin να είναι αυστηρός καθρέφτης του REST. Έτσι το ρήμα Given θα μπορούσε να σχεδιαστεί, έτσι ώστε και να μπορεί να περιγράφει ρόλους/ιεραρχίες, αλλά και να μπορεί να χρησιμοποιείται ελεύθερα.

6.2.3 Απεικόνιση μη λειτουργικών απαιτήσεων σε Gherkin

Το προτεινόμενο σύστημα σχεδιάστηκε με στόχο την επικοινωνία με τον πελάτη αλλά και των μηχανικών. Αν επικεντρωθούμε στην επικοινωνία των μηχανικών, τότε ίσως τους τελευταίους να ενδιέφερε η καταγραφή μη λειτουργικών απαιτήσεων επίσης σε Gherkin. Συγκερκιμένα, οι απαιτήσεις αυτές θα αφορούσαν την επικοινωνία του προγραμματιστή με τον tester του API. Οι περιγραφές των σεναρίων θα αφορούσαν κυρίως τους header των HTTP αιτημάτων και απαντήσεων. Η διαδικασία θα μπορούσε να συνδυαστεί με την αυτόματη παραγωγή test, η οποία φαίνεται να υποστηρίζεται από εργαλεία συμβατά με το OpenAPI Specification (π.χ. ο OAS-generated python flask server, παρέχει δυνατότητα δημιουργίας test με το πακέτο tox). Κεφάλαιο 6. Συμπεράσματα & Μελλοντικές επεκτάσεις 122

6.2.4 HATEOAS Graphs

Τα HATEOAS graphs μπορούν να αποτελέσουν ένα χρήσιμο εργαλείο τόσο για την επικοινωνία με τον πελάτη, όσο και για την μεταξύ των μηχανικών επικοινωνία. Παραδείγματος χάρη, ο πελάτης μπορεί να επιβεβαιώσει την επιτυχή σύλληψη του DAP, ενώ ο μηχανικός μπορεί να υπολογίσει γρήγορα χρόνους απόκρισης, καθώς μεταβαίνουμε από ένα resource ή application state σε ένα άλλο. Έτσι θα μπορούσαν παραδείγματος χάρη να υπάρχουν παραπάνω από ένας γράφοι, ένας για κάθε ρόλο. Ο γράφος του ρόλου θα έδειχνε μόνο τα resources/application state και τις συνδέσεις αυτών, όπου ο ρόλος θα είχε πρόσβαση. Επιπλέον ο γράφος του application state αναδεικνύει ότι το πόσο REST είναι ένα σύστημα, μπορεί να βεβαιωθεί μαθηματικά. Κατά Roy Fielding, πρέπει κάθε μετάβαση σε νέο ap- plication state να γίνεται με hypermedia. Αυτό σημαίνει ότι ο γράφος, πρέπει να είναι συνδεδεμένος. Δηλαδή πρέπει για κάθε ζευγάρι κορυφών (resources), να υπάρχει ένα μονοπάτι που τις συνδέει. Επίσης πρέπει αυτό το μονοπάτι να είναι κατευθυνόμενο. Εφόσον αυτό ισχύει, το σύστημα είναι REST ή Richardson Maturity level 3. Έτσι μπορεί να γραφεί κώδικας που ελέγχει την συνδεσιμότητα του γράφου και τυπώνει ανάλογο μήνυμα. Φυσικά η συνδεσιμότητα μπορεί να επιβεβαιωθεί με οπτική επισκόπηση του γράφου, αν μιλάμε για απλά συστήματα.

6.2.5 Τυποποίηση του NLP Model & IDE

Το μοντέλο που εξάγει το NLP Engine θα μπορούσε να τυποποιηθεί. Κάτι τέτοιο όμως κρίνεται ορθό, εφόσον το σύστημα έχει βρει αποδοχή. Έως τότε η τυποποίηση του NLP Model θα ήταν εκτεθειμένη σε συνεχής αλλαγές λόγω νέων χαρακτηριστικών. Παραδείγματος χάρη, κατά την ανάπτυξη του Gherkin2OAS το NLP model άλλαξε αρκετές φορές. Σε κάθε περίπτωση, μία τέτοια τυποποίηση θα προσέδιδε περαιτέρω διαδραστικότητα κατά την ανάπτυξη του API. Το επαρκώς τυποποιημένο NLP model θα μπορούσε να αποτελεί κομμάτι ενός ολοκληρωμένου περιβάλλοντος ανάπτυξης RESTful Web API (IDE). Σε ένα IDE θα μπορούσε να υπάρχει και Gherkin editor με συντακτικές ευαισθησίες προερχόμενες από την μεθοδολογία RDD. Στο IDE θα ενσωματωνόταν προφανώς και τα HATEOAS graph και επεκτάσεις αυτών, ο υπάρχων swagger editor ή παραλλαγή του και ενδεχόμενο testing utility.

6.2.6 OpenAPI Specification V3

Ενώ συγγράφονταν η διπλωματική, η συζήτηση για το OpenAPI Specification V3 ήταν ενεργή. Έχουμε ήδη δει ότι το OpenAPI Specification δεν υποστηρίζει το HATEOAS με φυσικό τρόπο. Η έλλειψη αυτής της ιδιότητας έγινε αντικείμενο συζήτησης στην κοινότητα12. Στις 24/01/2017, παρατέθηκε στο blog του OpenAPI Initiative3 το changelog με τις αλλαγές που πρόκειται να υλοποιηθούν στις 28/02/2017. Παραθέτουμε το Changelog ως έχει 1. Rearranged the structure of the specification for easier and extended reusability. 2. Extended JSON Schema support to include ‘oneOf‘, ‘anyOf‘ and ‘not‘ support.

1https://github.com/OAI/OpenAPI-Specification/issues/577 2http://nordicapis.com/evolution-openapi-specification-openapi-mean-open-world/ 3https://www.openapis.org/blog/2017/01/24/a-new-year-a-new-specification Κεφάλαιο 6. Συμπεράσματα & Μελλοντικές επεκτάσεις 123

3. Changed the structure of parameters to allow the use of schema in them. 4. Added support for Cookie parameters and eliminated dataForm parameters. 5. Body parameters were extracted to their own entity. 6. Added support for content type negotiation. 7. Introduced a new format to allow static linking between responses and future re- quests. 8. Simplified and enhanced security definitions of APIs. 9. Added a callback mechanism to describe WebHooks. Από αυτές τις αλλαγές σχολιάζουμε ότι: • Το OpenAPI Specification θα υποστηρίζει HATEOAS (7) • Η αφαίρεση των παραμέτρων τύπου dataForm και η αντιμετώπιση των body παραμέτρων ως ξεχωριστές οντότητες (4), (5), απλοποιούν το έργο του Formatter. Έτσι μελλοντική βελτιώση θα ήταν η ενημέρωση του Gherkin2OAS ώστε να υποστηρίζει το νέο version του OpenAPI Specification. 124 Παράρτημα A

Cucumber

Ένα από τα πιο ευρέως διαδεδομένα εργαλεία BDD, είναι το Cucumber. Το Cucum- ber ξεχωρίζει από τα υπόλοιπα, διότι τα τεστ του μπορούν να διαβαστούν και να γραφτούν από οποιονδήποτε στην ομάδα ανάπτυξης [32]. Είναι γραμμένο στην γλώσσα προγραμματισμού Ruby1. Η Ruby είναι αντικειμενοστραφής γλώσσα υψηλού επιπέδου. Βασικό της χαρακτηριστικό είναι το πολύ φιλικό στον προγραμματιστή συντακτικό της. Έτσι διακρίνεται από αναγνωσιμότητα και ευκολία συγγραφής. Το χαρακτηριστικό της δε αυτό έρχεται και κουμπώνει ιδανικά στην μεθοδολογία BDD. Ουσιαστικά αποτελεί την συγκολλητική ουσία μεταξύ User Stories και κώδικα (εικόνα A.1).

Εικόνα A.1: Τα βασικά επίπεδα του Cucumber [32]

Έτσι όχι μόνο διευκολύνει τα βήματα 1 και 2 του BDD αλλά και το βήμα 4. Αυτό διότι όντας η γλώσσα Ruby απλή και κατανοητή, καθιστά ευκολότερη την αντιστοίχηση των τεχνικών προβλημάτων (τα οποία προέκυψαν μετά την δοκιμή του User Story) στα User Stories. Δηλαδή διευκολύνει τους μηχανικούς στην επικοινωνία τους με τους πελάτες. Όλα τα εργαλεία BDD αποτελούνται από δύο βασικά στοιχεία:

• Την γλώσσα και τον τρόπο περιγραφής των User Stories • Τα εργαλεία μετατροπής των User Stories σε λειτουργικά test.

1https://www.ruby-lang.org/en/ Παράρτημα A. Cucumber 125

Στο Cucumber το πρώτο καλύπτεται από τα feature files και τη γλώσσα Gherkin, ενώ το δεύτερο από τα Step Definitions και φυσικά τη γλώσσα Ruby. Έτσι το Cucumber αποδομεί την διαδικασία BDD σε δύο βασικά στάδια

1. Business Facing Κατά το στάδιο αυτό γίνεται η συζήτηση με τους πελάτες και συγγράφονται τα User Stories 2. Technology Facing Κατά το στάδιο αυτό μετατρέπονται τα User Stories σε κώδικα και εκτελούνται τα τεστ

Στο Cucumber τα δύο αυτά στάδια αναλύονται σε ενδιάμεσα βήματα. Το σύνολο των βημάτων αποτελεί το Cucumber technology stack [32] το οποίο συνοψίζεται στην εικόνα A.2.

Εικόνα A.2: Cucumber testing stack: Η μεθοδολογία BDD κατά Cucumber [32]

A.1 Cucumber Business Facing

Το Cucumber Business Facing αποτελείται κυρίως από την γλώσσα Gherkin και τα fea- ture files, όπως περιγράφηκαν στο κεφάλαιο 2. Σε αυτά που περιγράφηκαν στο κεφάλαιο 2, προσθέτουμε και ένα ακόμα χαρακτηριστικό της Gherkin, το Scenario outline. Τα scenario outlines είναι σενάρια τα οποία υποστηρίζουν παραμέτρους. Περίπτωση αξιοποίησης του scenario outline μπορούμε να δούμε στα παραδείγματα A.1 και A.2. Στην περίπτωση αυτή βλέπουμε ότι τα δύο σενάρια του παραδείγματος A.1 διαφέρουν μόνο στα νούμερα. Άρα έχουμε πλεονάζουσα πληροφορία. Έτσι στο παράδειγμα A.2 τα νούμερα αντικαθίστανται από παραμέτρους και πλέον έχουμε 1 σενάριο. Η συμπλήρωση των παραμέτρων γίνεται μέσα από τα Examples, δηλαδή πίνακες παραδειγμάτων. Τα scenario outlines βελτιώνουν δραματικά την δουλειά του tester. Χάρη στους πίνακες Παράρτημα A. Cucumber 126

δοκιμών μπορεί να προκύψουν περιπτώσεις που ο πελάτης δεν έχει σκεφτεί ή ο μηχανικός δεν έχει καταλάβει. Για παράδειγμα ποιοι και πόσοι χαρακτήρες μπορούν να μπουν στο πεδίο ενός κωδικού. Ή τι συμβαίνει στην περίπτωση που χρήστης κάνει ανάληψη από λογαριασμό που έχει χρήματα, αλλά είναι ανενεργός και λήγει (frozen bank account) ενώ πραγματοποιείται η ανάληψη (edge case). Το τελευταίο αποτελεί ένα κλασσικό domain σενάριο που δύσκολα θα γνωρίζει ο μηχανικός.

Παράδειγμα A.1: Παράδειγμα A.2: Πλεονάζοντα σενάρια Cucumber Scenario Cucumber Outline Scenario: eat 5 out of 12 Scenario Outline: eating Given there are 12 cucumbers Given there are cucumbers When I eat 5 cucumbers When I eat cucumbers Then I should have 7 cucumbers Then I should have cucumbers

Scenario: eat 5 out of 20 Examples: Given there are 20 cucumbers | start | eat | left | When I eat 5 cucumbers | 12 | 5 | 7 | Then I should have 15 cucumbers | 20 | 5 | 15 |

Συνοψίζοντας το Business Facing του Cucumber περιλαμβάνει τα feature files με τα features, τα scenarios, τα steps και τα scenario outlines. Χάρη σε αυτά πετυχαίνει εύκολη συνεννόηση μεταξύ των πελατών και των μηχανικών, κοινό τρόπο σκέψης, δυνατότητα εισαγωγής όρων domain και διευκόλυνση στους μηχανικούς στην συγγραφή των τεστ και άρα στην ανάπτυξη του λογισμικού. Επίσης πρέπει εδώ να αναφέρουμε ότι το cucumber υποστηρίζει 68 γλώσσες χωρών για τα feature files, μεταξύ αυτών και Ελληνικά. Παράρτημα A. Cucumber 127

A.2 Cucumber Technology Facing

Αφού έχει ολοκληρωθεί το User Story, πλέον αναλαμβάνουν μόνο οι μηχανικοί λογισμικού. Τα feature files πρέπει να μετατραπούν σε κώδικα ώστε να μπορέσει να τα εκτελέσει ο υπολογιστής. Το κομμάτι αυτό αναλαμβάνει το Cucumber Technology Stack. Το μικρότερο δομικό στοιχείο των feature files είναι το step. Άρα η μετατροπή πρέπει να ξεκινήσει από την μεταγλώττιση των steps. Για τον λόγο αυτο το Cucumber εισάγει τα step definitions. Τα step definitions είναι κομμάτια κώδικα Ruby τα οποία αντιστοιχούν σε ένα step. Για παράδειγμα δεδομένου του step

Given I have $100 in my account

το αντίστοιχο step definition είναι το παράδειγμα A.3

Παράδειγμα A.3: cucumber step definition Given /I have \$100 in my Account/ do #TODO: code that puts $100 into User's Account goes here end

Αναλύοντας το παράδειγμα 2.5, βλέπουμε ότι η αντιστοίχιση γίνεται μέσω ενός Regular Expression1. Τα Regular Expressions είναι ακουλουθίες χαρακτήρων που εκφράζουν πρότυπα αναζήτησης σε κείμενο (search patterns). Δηλαδή το Cucumber εξετάζει το κείμενο του feature file και όποτε ένα Regular Expression συμπίπτει με κάποιο step, τότε εκτελείται το αντίστοιχο step definition. Αφού λοιπόν γραφεί ένα definition για κάθε step, μένει να γράψουμε τον κώδικα που θα εκτελείται. Ο κώδικας αυτός δεν είναι ο κώδικας του λογισμικού. Είναι κώδικας που αφορά την συγγραφή του τεστ. Δεν πρέπει να ξεχνάμε πως βασιζόμαστε στην διαδικασία TDD και άρα η ανάπτυξη του λογισμικού βασίζεται στα τεστ. Αφού γραφούν τα step definitions μπορούμε να αρχίσουμε να εκτελούμε τα τεστ. Κατά την συγγραφή των step definitions (ή και κατά την εκτέλεση των τεστ) μπορεί να χρειαστούμε και κάποιο support code. Για παράδειγμα εικονικές βάσεις δεδομένων, διεπαφές χρηστών κ.α.. Δηλαδή χρειαζόμαστε κλάσεις οι οποίες κατά την διάρκεια των τεστ θα έχουν αδιάφορο περιεχόμενο. Οι κλάσεις αυτές θα συμπληρωθούν με πραγματικά στοιχεία, όταν όλα τα τεστ έχουν περάσει και άρα έχουμε επιτυχημένο BDD. Η ανάγκη να δημιουργούμε το σύστημα ενώ γράφουμε τα τεστ, είναι εξ’ άλλου ο απώτερος στόχος του BDD. Η εκτέλεση του τεστ γίνεται με την βοήθεια automation library του Cucumber. Το automation li- brary παίρνει τα step definitions και το support code και εκτελεί το τεστ. Τέσσερα είναι τα πιθανά αποτελέσματα που εμφανίζει το Cucumber για σχετικά με την εκτέλεση των τεστ: • Passed Ο κώδικας έτρεξε χωρίς σφάλματα και το τεστ πέρασε • Failed Τα step definitions επέστρεψαν με σφάλμα, το τεστ δεν πέρασε • Undefined Το Cucumber δεν ξέρει πώς να τρέξει το step, γιατί δεν μπόρεσε να το αντιστοιχήσει σε step definition • Pending Το step definition έχει επισημανθεί ως ”pending” Στόχος της διαδικασίας BDD είναι προφανώς να περάσουν όλα τα τεστ του συστήματος. Τα step definitions λοιπόν παίζουν τον ρόλο του μεταγλωττιστή μεταξύ της γλώσσας Gherkin

1https://en.wikipedia.org/wiki/Regular_expression Παράρτημα A. Cucumber 128

και της Ruby (εικόνα A.3. Το λογικό διάγραμμα εκτέλεσης ενός σεναρίου αποτελούμενο από βήματα φαίνεται στην εικόνα A.4.

Εικόνα A.3: Τα step definitions παίζουν τον ρόλο του μεταγλωττιστή [32]

A.3 Άλλα εργαλεία BDD/ΤDD/ATDD

Πέρα από το Cucumber, αξιοσημείωτα εργαλεία, λεγόμενα και ως Test Automation Frame- works είναι τα: • Rspec (http://rspec.info/) To Rspec επιχειρεί να μετατρέψει την διαδικασία TDD σε λογική BDD. Έτσι τόσο τα User Stories όσο και τα τεστ γράφονται σε γλώσσα προγραμματισμού Ruby. • JBehave (http://jbehave.org/) Έχει παρόμοια απλά User Stories με το Cucumber, οι δοκιμές γίνονται σε γλώσσα προγραμματισμού Java. Οι δοκιμές του JBehave είναι πιο τεχνικές από αυτές του Cucumber • Behat (http://docs.behat.org/en/v3.0/) Το Behat έχει ακριβώς τα ίδια User Stories με το Cucumber. Η διαφορά του είναι ότι τα τεστ είναι γραμμένα σε γλώσσα PHP. Από την έκδοση 3 και μετά θεωρείται επίσημη υλοποίηση του Cucumber σε PHP. • Concordion (concordion.org) Τα User Stories είναι γραμμένα σε απλή φυσική γλώσσα. Η φυσική γλώσσα όμως περικλείεται από σήμανση HTML. Έτσι τα User Stories εξακολουθούν να είναι τεχνικά. Τα τεστ στο Concordion είναι γραμμένα σε Java. Παράρτημα A. Cucumber 129

Επίσης τα JDave, easyb, Nbehave (Java), Specflow (C#), Chakram (REST API testing framework αξιοποιώντας το BDD) κ.α.1

1http://www.qatestingtools.com/compare-bdd-testing-tools?&&items_per_page=15 Παράρτημα A. Cucumber 130

Εικόνα A.4: Πώς το Cucumber εκτελεί ένα σενάριο [32] 131 Παράρτημα B

Η τεχνολογία πριν το REST ή οι ανταγωνιστικές τεχνολογίες

Οι προγραμματιστές και οι μηχανικοί λογισμικού ανά τον κόσμο αξιοποίησαν την φιλικότητα του Παγκόσμιου Ιστού για την ανάπτυξη εφαρμογών. Πλέον το βασικό ερώτημα στον χώρο είναι: Πώς θα σχεδιάσουμε συστήματα και εφαρμογές που να συνεργάζονται καλά μεταξύ τους; Οι διάφορες εταιρείες και οργανισμοί που χρησιμοποιούσαν τον Παγκόσμιο Ιστό ανέπτυξαν τις δικές τους υλοποιήσεις προκειμένου να απαντήσουν σε αυτό το ερώτημα. Θα επισημαίνουμε εδώ αυτές που ξεχωρίζουν.

Ξεκαθαρίζουμε πρώτα το εξής. Πλέον μιλάμε αποκλειστικά για την προγραμματιστική φύση του Παγκόσμιου Ιστού. Έτσι, όπως είχαμε αναφέρει στο τέλος της ενότητας 1.2, μιλάμε για υπηρεσίες Παγκόσμιου Ιστού (Web Services). Υπό αυτή την σκοπιά υπενθυμίζουμε τα εμπλεκόμενα μέρη: • Καταναλωτές υπηρεσιών Παγκόσμιου Ιστού (Web Service Consumers). Δηλαδή οι εφαρμογές που αναπτύσσουν οι προγραμματιστές και οι μηχανικοί λογισμικού. • Πάροχοι υπηρεσιών Παγκόσμιου Ιστού (Web Service Providers). Δηλαδή οι διάφορες εταιρείες, οι οργανώσεις και οι φορείς που διαθέτουν την επιχειρηματική τους διαδικασία προς αξιοποίηση από τους καταναλωτές. Έτσι πλέον δεν θα μιλάμε για πελάτες και εξυπηρετητές, όπως κάναμε στο πρωτόκολλο HTTP, αλλά για καταναλωτές και παρόχους υπηρεσιών Παγκόσμιου Ιστού.

B.1 URI Tunneling με URI Templates

Ένα URI Template είναι ένα URI το οποίο δεν είναι ολοκληρωμένο. Κομμάτι του URI περιμένει να συμπληρωθεί από τον καταναλωτή υπηρεσίας ανάλογα με τις ανάγκες του τελευταίου. Ένα τέτοιο URI Template παρουσιάζεται στον προγραμματιστή με τον εξής τρόπο: http://restbucks.com/order/{order_id}

όπου το {order_id} είναι το template. Το order_id είναι ο αριθμός παραγγελίας και αλλάζει ανάλογα με την παραγγελία. Παρόμοια στο παράδειγμα με τα βίντεο του youtube: http://youtube.com/watch?v={video_id}

εδώ το {video_id} είναι το Template.

To URI tunneling χρησιμοποιεί URI Templates για να κωδικοποιήσει όλη την Παράρτημα B. Η τεχνολογία πριν το REST ή οι ανταγωνιστικές τεχνολογίες 132

πληροφορία που θέλει να στείλει στον πάροχο της υπηρεσίας. Έτσι για παράδειγμα, για μία παραγγελία καφέ στο http://restbucks.com μέσω URI Tunneling, το αίτημα έχει την εξής μορφή: http://restbucks.com/ PlaceOrder?coffee=latte&size=large&milk=whole&location=takeAway

το οποίο αντιστοιχεί στο παρακάτω URI Template http://restbucks.com/ PlaceOrder?coffee={type}&size={size}&milk={milk}&location={location}

Έτσι το resource ”Παραγγελία” του καταστήματος, παραμετροποιείται μέσω του URI Template και αποστέλλεται η παραγγελία στο κατάστημα. Η όλη διαδικασία προϋποθέτει ότι η υπηρεσία ιστού του καταστήματος, έχει σχεδιαστεί ώστε να λειτουργεί με URI Tunneling. Το URI Tunneling χρησιμοποιείται και σήμερα αλλά όχι σαν συνολική λύση. Αυτό διότι η ενσωμάτωση όλης της επιχειρισιακής διαδικασίας μιας εταιρείας σε URIs δεν προτιμάται, για πρακτικούς λόγους. Γι’ αυτό τον λόγο εμφανίστηκε το στυλ σχεδιασμού RPC.

B.2 RPC και REST-RPC Hybrid

Κατά τoν τρόπο σχεδιασμού RPC (Remote Procedure Calls), τα αιτήματα προς έναν παροχέα υπηρεσίας ιστού εμπεριέχονται μέσα στο HTTP αίτημα. Έτσι αντί να έχουμε παραμετροποιημένα URIs, έχουμε αιτήματα HTTP, τα οποία εμπεριέχουν εσωτερικά την κλήση μιας διαδικασίας στον πάροχο της υπηρεσίας. Αυτή η, ενσωματωμένη στο HTTP αίτημα, κλήση διαδικασίας, είναι ουσιαστικά ένα ενσωματώμένο έγγραφο. Τέτοια έγγραφα μπορούν παραδείγματος χάρη να έχουν μορφοποίηση XML. Παράδειγμα ενός τέτοιο εγγράφου σε XML είναι το παρακάτω:

Παράδειγμα B.1: Remote Procedure Call με XML lookupUPC 001441000055

Η κλήση της διαδικασίας εδώ φαίνεται καθαρά. Άλλο είδος κλήσης διαδικασίας με έγγραφα XML είναι το Παράδειγμα B.2. Στο παράδειγμα αυτό παρατηρούμε ότι δεν έχουμε την αυστηρή ορολογία methodcall. Η υπηρεσία έχει σχεδιαστεί έτσι ώστε, όταν παραλαμβάνει ένα XML έγγραφο ”Order”, να το αντιμετωπίζει σαν παραγγελία. Η συγκεκριμένη μεθοδολογία σχεδιασμού ονομάζεται POX (Plain Old XML) over HTTP. Μάλιστα η συγκεκριμένη δεν εντάσσεται στην αυστηρά RPC τεχνολογία και θα μπορούσε Παράρτημα B. Η τεχνολογία πριν το REST ή οι ανταγωνιστικές τεχνολογίες 133

κάποιος να την εντάξει στην RPC-REST Hybrid. Επισημαίνεται ότι στις μεθοδολογίες τύπου RPC ο προσδιορισμός των resources εξακολουθεί να γίνεται με URIs αλλά όχι με URI Templates.

Παράδειγμα B.2: POX μέσω HTTP takeAway latte 1 whole small cookie chocolate−chip 2

Οι RPC-REST Hybrid τεχνολογίες είναι τεχνολογίες που εξακολουθούν να βασίζονται στον RPC τρόπο σκέψης, αλλά ταυτόχρονα έχουν ενσωματώσει και κομμάτια του στυλ σχεδιασμού REST. Γενικώς ανάμεσα στις υπηρεσίες ιστού και στις καθαρά RESTful υπηρεσίες υπάρχει μία μεγάλη γκάμα ενδιάμεσων λύσεων. Οι λύσεις αυτές συναποτελούν το λεγόμενο WS Stack ή WS-*.

B.3 WS-*

Με τον όρο WS-* αναφερόμαστε σε ένα σύνολο πρωτοκόλλων για την επικοινωνία εφαρμογών στον Παγκόσμιο Ιστό. Τα διάφορα πρωτόκολλα που το αποτελούν -η λεγόμενη ’στοίβα’ (stack)-, έχουν αναπτυχθεί μέσω διάφορων πρωτοβουλιών της βιομηχανίας. Κοινό τους χαρακτηριστικό είναι ότι σχεδιάστηκαν για να εξυπηρετήσουν ανάγκες ειδικών συστημάτων και όχι του Παγκόσμιου Ιστού ως σύνολο. Τα πιο γνωστά από αυτά είναι το SOAP και το WSDL. Το SOAP είναι ένα πρωτόκολλο περιγραφής πληροφορίας. Κατά το SOAP, το HTTP μήνυμα ενθυλακώνεται σε έναν φάκελο:

Παράδειγμα B.3: SOAP Envelope POST /InStock HTTP/1.1 Host: www.example.org Content−Type: application/soap+xml; charset=utf−8 Content−Length: 299 SOAPAction: "http://www.w3.org/2003/05/soap−envelope"

IBM Παράρτημα B. Η τεχνολογία πριν το REST ή οι ανταγωνιστικές τεχνολογίες 134

Η λογική της ενθυλάκωσης μηνυμάτων καθιστά το SOAP ικανό να αξιοποιείται από οποιονδήποτε καταλαβαίνει το πρωτόκολλο SOAP. Από την άλλη, οι SOAP φάκελοι καταλήγουν να είναι εξαιρετικά αναλυτικοί. Αυτό διότι το SOAP εξυπηρετεί την μετάδοση μηνυμάτων και όχι την επικοινωνία εφαρμογών. Επιπρόσθετα η μεθοδολογίες επεξεργασίας της αναπαράστασης XML δεν είναι επαρκώς γρήγορες. Έτσι του SOAP υπερίσχυσαν πρωτόκολλα που χρησιμοποιούν το HTTP πιο άμεσα, όπως το REST. Το Web Services Description Language ή WSDL από την άλλη, έχει ομοιότητες με την λογική του OpenAPI Specification. Είναι μία γλώσσα περιγραφής υπηρεσιών Παγκόσμιου Ιστού. Συνήθως χρησιμοποιείται μαζί με το SOAP. Ο καταναλωτής υπηρεσίας διαβάζει το αρχείο WSDL και πραγματοποιεί αιτήματα προς την υπηρεσία με το πρωτόκολλο SOAP. Μειονέκτημά του ότι οι νεότερες εκδόσεις του δεν υποστηρίζουν αρκετά εργαλεία ανάπτυξης λογισμικού.

Παράδειγμα B.4: Παράδειγμα WSDL αρχείου

This is a sample WSDL 2.0 document.

... ...

Παράρτημα B. Η τεχνολογία πριν το REST ή οι ανταγωνιστικές τεχνολογίες 135

Δύο σημεία μας ενδιαφέρουν από αυτές τις τεχνολογίες αλλά τις προηγούμενες που αναφέραμε. Το πρώτο είναι ότι με την ύπαρξή τους, επιβεβαιώνουν την χρησιμότητα του Παγκόσμιου Ιστού ως πλατφόρμα εφαρμογών. Το πιο ενδιαφέρον σημείο όμως είναι το ακόλουθο. Οι τεχνολογίες αυτές δεν καταφέρνουν να αξιοποιήσουν στο έπακρο την αρχιτεκτονική του Παγκόσμιου Ιστού. Περισσότερο χρησιμοποιούν τον Παγκόσμιο Ιστό ως ένα μέσο επικοινωνίας και όχι ως πλατφόρμα εφαρμογών. Εντάσσουν την λογική των εφαρμογών τους μέσα στα μηνύματα HTTP. Έτσι υλοποιούν πρωτόκολλα εφαρμογών τα οποία έχουν να κάνουν με την συγκεκριμένη εφαρμογή. Ξεχνούν όμως ότι το πρωτόκολλο HTTP δεν είναι πρωτόκολλο μετάδοσης μηνυμάτων, αλλά πρωτόκολλο εφαρμογών. Έτσι πραγματοποιούν το παράδοξο να αναπτύσσουν πρωτόκολλα εφαρμογών πάνω σε υπάρχων πρωτόκολλο εφαρμογών. Φυσικά αυτό δεν σημαίνει ότι οι προγραμματιστές και οι μηχανικοί λογισμικού δεν αντιλαμβάνονται αυτό το παράδοξο σχήμα. Απλώς σημαίνει (για άλλη μια φορά) ότι οι ανάγκες και οι ρυθμοί της εποχής οδήγησαν τις εταιρίες, τις οργανώσεις και την βιομηχανία λογισμικού, να εφεύρουν τεχνολογίες που έλυναν άμεσα το πρόβλημά τους. Τώρα η εμπειρία και άρα η νέα τάση της εποχής, δείχνουν πως αυτό το μοντέλο ανάπτυξης υπηρεσιών πρέπει να αναθεωρηθεί. 136 Παράρτημα C

Απαιτήσεις API κατά RDD & OpenAPI Specifications

C.1 Mytop10

Στην ενότητα αυτή παρατίθενται τα resource files που περιγράφουν το API της web εφαρμογής Mytop101. Επίσης παρατίθεται το OpenAPI Specification που δημιουργήθηκε από αυτά.

Παράδειγμα C.1: Mytop10 με RDD: user.resource Feature: user

Scenario: Create user Creates a single user Given that I am authorized as administrator When I create a user: | email | `[email protected]` | | username | `Tasos` | | password | ******** | | id | 250 | | date of birth | 04/05/1992 | | sex | `male` | | location | `Thessaloniki` | | photo | `http://photo.com/myphoto` | | status | `online` | | trophy | `name` | Then I should see a message "Successfull new account" # And I should be prompted to create a follow list

Scenario: Attempt to create user while not being authorized # Given that I am not authorized to create users When I attempt to create, view, delete or update the user Then I should see a message "You are unauthorized to make this request."

Scenario: View user`s details Shows details of single user When I request a user by his id Then I should see his username | username | `Tasos` |

Scenario: User does not exist # Given that the user does not exist When I request, update or delete a user by his id Then I should see "User doesn`t exist"

1https://github.com/SteliosArakliotis/ErgasiaSaaS Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 137

Scenario: Delete user Deletes a single user When I delete a user by his id Then I should see "User deleted successfully"

Scenario: Update user profile Update your user profile When I update a user by his id And I specify the following information | username | `Nick` | | | password | ******* | min length of 8 | | date of birth | 09−08−1002 | | | sex | `Male` | | | location | `Sweden` | | | photo | `http://imgur.com/rand_photo` | | Then I should see the message "Successfully updated"

Scenario: Check user`s status Returns status about a single user. Valid status requests are `online`, `offline`, `away` and `busy`. The response will be "is " When I request a user by his id And I also request his status | status | `online` | Then I should see | username | "Michalis Pap " | | status | "is online" |

Scenario: Award trophy Give trophy to particular user. When I update a user by it`s id And I award a | trophy | `trophytype` | Then I should see the message "Successfully awarded"

Παράδειγμα C.2: Mytop10 με RDD: admin.resource Feature: Manage administrators

Background: Given that I am authorized as system

Scenario: Create a new administrator Creates a new single administrator. When I create a new administrator: | admin name | `ADMIN01` | | admin id | 1 | Then I should see "Successfull new admin account"

Scenario: View admin`s details Returns data about a single administrator. When I check an admin by his id Then I should see "OK" And the details of the admin | admin_id | 123 | | username | "Kostas Sotiriou" |

Scenario: Retrieve non existent admin When I check an admin by his id Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 138

# And there is no such admin Then I should see "Admin doesn`t exist"

Παράδειγμα C.3: Mytop10 με RDD: comment.resource Feature: Comment a list

Background: Given a list id

Scenario: Comment list Comment a list of a particular user. When I create a new comment: | comment content | `I like most of your list` | | comment id | 12 | Then I should see "List commented successfully"

Παράδειγμα C.4: Mytop10 με RDD: follow list.resource Feature: follow list

Background: Given a user`s id

Scenario: When I create a new followlist: | users | [1,5,7,12,10] | maximum of 10000 | Then I should see `OK`

Παράδειγμα C.5: Mytop10 με RDD: list.resource Feature: lists

Background: Lists belong to users Given a user`s id

Scenario: Create new list Create a new single list for a user. When I create a list | id | 30 | | category | `series` | | listname | `top 10 series` | | description | `Best series since 1990` | | date of release | 05/06/2010 | | tag | `mystery` | Then I could see "List created"

Scenario: Unsuccessfull list creation # Given WW3 When I create a list | id | 30 | | category | `series` | | listname | `top 10 series` | | description | `Best series since 1990` | | date of release | 05/06/2010 | | tag | `mystery` | Then I could see "List not created" Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 139

Scenario: Retrieve list Returns a single list of a particular user. When I check a list by it`s id Then I should see it`s name

Scenario: non existing list # Given a list does not exist When I try to view, delete or change a list by it`s id Then I should see "List doesn`t exist"

Scenario: Anauthorized list viewing and editing When I request or delete a list by it`s id Then I should see "You are unauthorized to make this request."

Scenario: Delete list Delete a single list of a particular user. When I remove a list by it`s id Then I should see "List deleted successfully"

Scenario: View all the lists Returns all lists of a particular user. When I submit an all list retrieval as follows | all | true | Then I should see "OK"

Scenario: Lists don`t exist #Given user has no list When I submit a request for all the user`s lists by specifying | all | true | Then I should see "There are no lists"

Scenario: Unauthorized to retrieve lists #Given that I don`t have required authorization When I submit a request for all lists | all | true | Then I should see "You are unauthorized to make this request."

Scenario: Change list name: Change a name of a single list. When I change a list by it`s id And I specify a list name as the changed value |listname| `movies`| Then I should see "Listname changed successfully"

Παράδειγμα C.6: Mytop10 με RDD: rate.resource Feature: rate lists

Background: Given a list id

Scenario: Rate a list When I submit a rating for a list: # parameter names as described by product owners | ratio | 7 | | ratio id | 4 | Then I should see "OK, list rated" Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 140

Scenario: Rate a non existent list When I submit a rating for a list: | ratio | 7 | | ratio id | 4 | # And the list does not exist Then I should see "List doesn`t exist"

Scenario: Unauthorized list When I submit a rating for a list: | ratio | 7 | | ratio id | 4 | # And I`m not authorized to do so Then I should see "You are unauthorized to make this request."

Παράδειγμα C.7: Mytop10 με RDD: search.resource Feature: Search functionality for the system

Scenario: Search for a user Returns data about a single user. When I search for a user And I specify a username Then I should see the user`s short details | email | `[email protected]` | | username | `Tasos` | | id | 250 | | date of birth | 04/05/1992 | And I should see the message "User found"

Scenario: Search for a list Returns data about a single list. When I search for a list And I specify |listname| `movies`| Then I should see the list`s short details | id | 30 | | category | `series` | | description | `Best series since 1990` | And I should see the message "List found"

Scenario: Search for a list by release date Returns data about a single list. When I search for a list And I specify |date of release| 19/02/2017| Then I should see the list`s short details | id | 30 | | category | `series` | | description | `Best series since 1990` | | date of release | 05/06/2010 | And I should see the message "List found"

Scenario: Search for lists with the bigest ratio Returns the lists with the bigest ratio. When I search for a list And I specify | ratio | 5 | | sort | `descending` | Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 141

Then I should see a sorted by ratio list of lists | sorted list | [`highest ratio listname`,`medium ratio listname`,\ `lowest ratio listname`] | maximum 15 items | And I should see "OK"

Scenario: Unauthorized search # Given that I`m unauthorized When I search And I specify for example | ratio | 5 | | sort | `descending` | Then I should see "You are unauthorized to make this request."

Scenario: Search query has no results When I search And I specify for example | ratio | 5 | | sort | `descending` | # And there are no results Then I should see `none found` Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 142

OpenAPI Specification:

Παράδειγμα C.8: Mytop 10 με RDD: OpenAPI Specification 1 { 2 ” paths ” : { 3 ”/ user /{ user_id }” : { 4 ” get ” : { 5 ”description” : ”- \tReturns status about a single user. Valid status requests are ’online’ , ’ o f f l i n e ’ , ’away’ and\n\t’busy’. The response will be \”is \”\n- \tShows details of single user” , 6 ”responses” : { 7 ” d e f a u l t ” : { 8 ”description” : ”None” , 9 ”schema” : { 10 ” $ r e f ” : ”#/ d e f i n i t i o n s / user_get_default_response” 11 } 12 } , 13 ”401” : { 14 ”description” : ”You are unauthorized to make this request.” 15 } , 16 ”404” : { 17 ”description” : ”User doesn’t exist” 18 } 19 } , 20 ”parameters” : [ 21 { 22 ”name” : ” s t a t u s ” , 23 ” in ” : ” query ” , 24 ” r e q u i r e d ” : f a l s e , 25 ” type ” : ” s t r i n g ” 26 } , 27 { 28 ”name” : ” user_id ” , 29 ” format ” : ” i n t 32” , 30 ” in ” : ” path ” , 31 ” r e q u i r e d ” : true , 32 ” type ” : ” i n t e g e r ” 33 } 34 ] 35 } , 36 ” d e l e t e ” : { 37 ”description” : ”- \tDeletes a single user” , 38 ”responses” : { 39 ”200” : { 40 ”description” : ”User deleted successfully” 41 } , 42 ”404” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 143

43 ”description” : ”User doesn’t exist” 44 } 45 } , 46 ”parameters” : [ 47 { 48 ”name” : ” user_id ” , 49 ” format ” : ” i n t 32” , 50 ” in ” : ” path ” , 51 ” r e q u i r e d ” : true , 52 ” type ” : ” i n t e g e r ” 53 } 54 ] 55 } , 56 ” put ” : { 57 ”description” : ”- \tUpdate your user profile\n- \ tGive trophy to particular user.” , 58 ”responses” : { 59 ”200” : { 60 ”description” : ”Successfully updated” 61 } , 62 ”401” : { 63 ”description” : ”You are unauthorized to make this request.” 64 } , 65 ”404” : { 66 ”description” : ”User doesn’t exist” 67 } 68 } , 69 ”parameters” : [ 70 { 71 ”name” : ”user_put_request_body” , 72 ”schema” : { 73 ” $ r e f ” : ”#/ d e f i n i t i o n s / user_put_request_body” 74 } , 75 ” in ” : ”body” 76 } , 77 { 78 ”name” : ” user_id ” , 79 ” format ” : ” i n t 32” , 80 ” in ” : ” path ” , 81 ” r e q u i r e d ” : true , 82 ” type ” : ” i n t e g e r ” 83 } 84 ] 85 } 86 } , 87 ”/admin/{admin_id}” : { 88 ” get ” : { 89 ”description” : ”- \tReturns data about a single administrator.” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 144

90 ”responses” : { 91 ”200” : { 92 ”description” : ”OK” , 93 ”schema” : { 94 ” $ r e f ” : ”#/definitions/admin_get_200 _response ” 95 } 96 } , 97 ”404” : { 98 ”description” : ”Admin doesn’t exist” 99 } 100 } , 101 ” s e c u r i t y ” : [ 102 { 103 ” system ” : [ 104 ” get : /admin/{ id }” 105 ] 106 } 107 ] , 108 ”parameters” : [ 109 { 110 ”name” : ”admin_id” , 111 ” format ” : ” i n t 32” , 112 ” in ” : ” path ” , 113 ” r e q u i r e d ” : true , 114 ” type ” : ” i n t e g e r ” 115 } 116 ] 117 } 118 } , 119 ”/ user ” : { 120 ” post ” : { 121 ”description” : ”- \tCreates a single user” , 122 ”responses” : { 123 ”200” : { 124 ”description” : ”Successfull new account” 125 } , 126 ”401” : { 127 ”description” : ”You are unauthorized to make this request.” 128 } 129 } , 130 ” s e c u r i t y ” : [ 131 { 132 ”administrator” : [ 133 ” post : / user ” 134 ] 135 } 136 ] , 137 ”parameters” : [ 138 { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 145

139 ”name” : ”user_post_request_body” , 140 ”schema” : { 141 ” $ r e f ” : ”#/ d e f i n i t i o n s / user_post_request_body” 142 } , 143 ” in ” : ”body” 144 } 145 ] 146 } 147 } , 148 ”/ user /{ user_id }/ l i s t /{ l i s t _ i d }/comment” : { 149 ” post ” : { 150 ”description” : ”- \tComment a list of a particular user . ” , 151 ”responses” : { 152 ”200” : { 153 ”description” : ”List commented successfully ” 154 } 155 } , 156 ”parameters” : [ 157 { 158 ”name” : ”comment_post_request_body” , 159 ”schema” : { 160 ” $ r e f ” : ”#/ d e f i n i t i o n s / comment_post_request_body” 161 } , 162 ” in ” : ”body” , 163 ” r e q u i r e d ” : true 164 } , 165 { 166 ”name” : ” user_id ” , 167 ” format ” : ” i n t 32” , 168 ” in ” : ” path ” , 169 ” r e q u i r e d ” : true , 170 ” type ” : ” i n t e g e r ” 171 } , 172 { 173 ”name” : ” l i s t _ i d ” , 174 ” format ” : ” i n t 32” , 175 ” in ” : ” path ” , 176 ” r e q u i r e d ” : true , 177 ” type ” : ” i n t e g e r ” 178 } 179 ] 180 } 181 } , 182 ”/admin” : { 183 ” post ” : { 184 ”description” : ”- \tCreates a new single administrator.” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 146

185 ”responses” : { 186 ”200” : { 187 ”description” : ”Successfull new admin account ” 188 } 189 } , 190 ” s e c u r i t y ” : [ 191 { 192 ” system ” : [ 193 ” post : /admin” 194 ] 195 } 196 ] , 197 ”parameters” : [ 198 { 199 ”name” : ”admin_post_request_body” , 200 ”schema” : { 201 ” $ r e f ” : ”#/ d e f i n i t i o n s / admin_post_request_body” 202 } , 203 ” in ” : ”body” , 204 ” r e q u i r e d ” : true 205 } 206 ] 207 } 208 } , 209 ”/ user /{ user_id }/ l i s t /{ l i s t _ i d }” : { 210 ” get ” : { 211 ”description” : ”- \tReturns a single list of a particular user.” , 212 ”responses” : { 213 ” d e f a u l t ” : { 214 ”description” : ”None” , 215 ”schema” : { 216 ” $ r e f ” : ”#/ d e f i n i t i o n s / list_get_default_response” 217 } 218 } , 219 ”401” : { 220 ”description” : ”You are unauthorized to make this request.” 221 } , 222 ”404” : { 223 ”description” : ”List doesn’t exist” 224 } 225 } , 226 ”parameters” : [ 227 { 228 ”name” : ” user_id ” , 229 ” format ” : ” i n t 32” , 230 ” in ” : ” path ” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 147

231 ” r e q u i r e d ” : true , 232 ” type ” : ” i n t e g e r ” 233 } , 234 { 235 ”name” : ” l i s t _ i d ” , 236 ” format ” : ” i n t 32” , 237 ” in ” : ” path ” , 238 ” r e q u i r e d ” : true , 239 ” type ” : ” i n t e g e r ” 240 } 241 ] 242 } , 243 ” d e l e t e ” : { 244 ”description” : ”- \tDelete a single list of a particular user.” , 245 ”responses” : { 246 ”200” : { 247 ”description” : ”List deleted successfully” 248 } , 249 ”401” : { 250 ”description” : ”You are unauthorized to make this request.” 251 } 252 } , 253 ”parameters” : [ 254 { 255 ”name” : ” user_id ” , 256 ” format ” : ” i n t 32” , 257 ” in ” : ” path ” , 258 ” r e q u i r e d ” : true , 259 ” type ” : ” i n t e g e r ” 260 } , 261 { 262 ”name” : ” l i s t _ i d ” , 263 ” format ” : ” i n t 32” , 264 ” in ” : ” path ” , 265 ” r e q u i r e d ” : true , 266 ” type ” : ” i n t e g e r ” 267 } 268 ] 269 } , 270 ” put ” : { 271 ”description” : ”- \tChange a name of a single list .” , 272 ”responses” : { 273 ”200” : { 274 ”description” : ”Listname changed successfully” 275 } , 276 ”404” : { 277 ”description” : ”List doesn’t exist” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 148

278 } 279 } , 280 ”parameters” : [ 281 { 282 ”name” : ”list_put_request_body” , 283 ”schema” : { 284 ” $ r e f ” : ”#/ d e f i n i t i o n s / list_put_request_body” 285 } , 286 ” in ” : ”body” 287 } , 288 { 289 ”name” : ” user_id ” , 290 ” format ” : ” i n t 32” , 291 ” in ” : ” path ” , 292 ” r e q u i r e d ” : true , 293 ” type ” : ” i n t e g e r ” 294 } , 295 { 296 ”name” : ” l i s t _ i d ” , 297 ” format ” : ” i n t 32” , 298 ” in ” : ” path ” , 299 ” r e q u i r e d ” : true , 300 ” type ” : ” i n t e g e r ” 301 } 302 ] 303 } 304 } , 305 ”/ user /{ user_id }/ l i s t ” : { 306 ” post ” : { 307 ”description” : ”- \tCreate a new single list for a user.\n- \tReturns all lists of a particular user . ” , 308 ”responses” : { 309 ”200” : { 310 ”description” : ”OK” 311 } , 312 ”401” : { 313 ”description” : ”You are unauthorized to make this request.” 314 } , 315 ”404” : { 316 ”description” : ”There are no lists” 317 } , 318 ”201” : { 319 ”description” : ”List created” 320 } 321 } , 322 ”parameters” : [ 323 { 324 ”name” : ”list_post_request_body” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 149

325 ”schema” : { 326 ” $ r e f ” : ”#/ d e f i n i t i o n s / list_post_request_body” 327 } , 328 ” in ” : ”body” 329 } , 330 { 331 ”name” : ” user_id ” , 332 ” format ” : ” i n t 32” , 333 ” in ” : ” path ” , 334 ” r e q u i r e d ” : true , 335 ” type ” : ” i n t e g e r ” 336 } 337 ] 338 } 339 } , 340 ”/ user /{ user_id }/ l i s t /{ l i s t _ i d }/ r a t e ” : { 341 ” post ” : { 342 ”responses” : { 343 ”200” : { 344 ”description” : ”OK, l i s t rated ” 345 } , 346 ”401” : { 347 ”description” : ”You are unauthorized to make this request.” 348 } , 349 ”404” : { 350 ”description” : ”List doesn’t exist” 351 } 352 } , 353 ”parameters” : [ 354 { 355 ”name” : ”rate_post_request_body” , 356 ”schema” : { 357 ” $ r e f ” : ”#/ d e f i n i t i o n s / rate_post_request_body” 358 } , 359 ” in ” : ”body” , 360 ” r e q u i r e d ” : true 361 } , 362 { 363 ”name” : ” user_id ” , 364 ” format ” : ” i n t 32” , 365 ” in ” : ” path ” , 366 ” r e q u i r e d ” : true , 367 ” type ” : ” i n t e g e r ” 368 } , 369 { 370 ”name” : ” l i s t _ i d ” , 371 ” format ” : ” i n t 32” , 372 ” in ” : ” path ” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 150

373 ” r e q u i r e d ” : true , 374 ” type ” : ” i n t e g e r ” 375 } 376 ] 377 } 378 } , 379 ”/ search ” : { 380 ” get ” : { 381 ”description” : ”- \tReturns data about a single user.\n- \tReturns data about a single list.\n- \tReturns the lists with the bigest ratio.\n- \ tReturns data about a single list.” , 382 ”responses” : { 383 ” d e f a u l t ” : { 384 ”description” : ”None” , 385 ”schema” : { 386 ” $ r e f ” : ”#/ d e f i n i t i o n s / search_get_default_response” 387 } 388 } , 389 ”401” : { 390 ”description” : ”You are unauthorized to make this request.” 391 } , 392 ”200” : { 393 ”description” : ”OK” , 394 ”schema” : { 395 ” $ r e f ” : ”#/definitions/search_get_ 200 _response ” 396 } 397 } , 398 ”404” : { 399 ”description” : ”none found” 400 } 401 } , 402 ”parameters” : [ 403 { 404 ”name” : ” username ” , 405 ” in ” : ” query ” , 406 ” r e q u i r e d ” : f a l s e , 407 ” type ” : ” s t r i n g ” 408 } , 409 { 410 ”name” : ” listname ” , 411 ” in ” : ” query ” , 412 ” r e q u i r e d ” : f a l s e , 413 ” type ” : ” s t r i n g ” 414 } , 415 { 416 ”name” : ” r a t i o ” , 417 ” format ” : ” i n t 32” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 151

418 ” in ” : ” query ” , 419 ” r e q u i r e d ” : f a l s e , 420 ” type ” : ” i n t e g e r ” 421 } , 422 { 423 ”name” : ” s o r t ” , 424 ” in ” : ” query ” , 425 ” r e q u i r e d ” : f a l s e , 426 ” type ” : ” s t r i n g ” 427 } , 428 { 429 ”name” : ”date of release” , 430 ” format ” : ” date ” , 431 ” in ” : ” query ” , 432 ” r e q u i r e d ” : f a l s e , 433 ” type ” : ” s t r i n g ” 434 } 435 ] 436 } 437 } , 438 ”/ user /{ user_id }/follow_list” : { 439 ” post ” : { 440 ”responses” : { 441 ”200” : { 442 ”description” : ”OK” 443 } 444 } , 445 ”parameters” : [ 446 { 447 ”name” : ”follow_list_post_request_body” , 448 ”schema” : { 449 ” $ r e f ” : ”#/ d e f i n i t i o n s / follow_list_post_request_body” 450 } , 451 ” in ” : ”body” , 452 ” r e q u i r e d ” : true 453 } , 454 { 455 ”name” : ” user_id ” , 456 ” format ” : ” i n t 32” , 457 ” in ” : ” path ” , 458 ” r e q u i r e d ” : true , 459 ” type ” : ” i n t e g e r ” 460 } 461 ] 462 } 463 } 464 } , 465 ” produces ” : [ 466 ”application/json” 467 ] , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 152

468 ” i n f o ” : { 469 ”description” : ”Create favorite lists” , 470 ” t i t l e ” : ”Mytop10” , 471 ”termsOfService” : ”” , 472 ” v e r s i o n ” : ”1” , 473 ” contact ” : { 474 ”name” : ”G. D. , E.G. , S.A.” , 475 ” u r l ” : ”” , 476 ” email ” : ”” 477 } , 478 ” l i c e n s e ” : { 479 ”name” : ”” , 480 ” u r l ” : ” https : //github.com/SteliosArakliotis/ ErgasiaSaaS” 481 } 482 } , 483 ”securityDefinitions” : { 484 ”administrator” : { 485 ”authorizationUrl” : ” http : //swagger. io/api/oauth/dialog ” , 486 ” scopes ” : { 487 ” post : / user ” : ”No description” 488 } , 489 ” flow ” : ” i m p l i c i t ” , 490 ” type ” : ” oauth 2” 491 } , 492 ” system ” : { 493 ”authorizationUrl” : ” http : //swagger. io/api/oauth/dialog ” , 494 ” scopes ” : { 495 ” post : /admin” : ”No description” , 496 ” get : /admin/{ id }” : ”No description” 497 } , 498 ” flow ” : ” i m p l i c i t ” , 499 ” type ” : ” oauth 2” 500 } 501 } , 502 ” host ” : ”localhost” , 503 ”definitions” : { 504 ”list_put_request_body” : { 505 ” example ” : [ 506 { 507 ” listname ” : ” movies ” 508 } 509 ] , 510 ”properties” : { 511 ” listname ” : { 512 ” type ” : ” s t r i n g ” 513 } 514 } , 515 ” type ” : ” o b j e c t ” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 153

516 } , 517 ”comment_post_request_body” : { 518 ” r e q u i r e d ” : [ 519 ”comment” 520 ] , 521 ”properties” : { 522 ”comment” : { 523 ” $ r e f ” : ”#/definitions/comment” 524 } 525 } , 526 ” type ” : ” o b j e c t ” 527 } , 528 ”admin_get_200 _response ” : { 529 ” example ” : [ 530 { 531 ” username ” : ”Kostas Sotiriou” , 532 ”admin_id” : 123 533 } 534 ] , 535 ” r e q u i r e d ” : [ 536 ”admin_id” , 537 ” username ” 538 ] , 539 ”properties” : { 540 ” username ” : { 541 ” type ” : ” s t r i n g ” 542 } , 543 ”admin_id” : { 544 ” format ” : ” i n t 32” , 545 ” type ” : ” i n t e g e r ” 546 } 547 } , 548 ” type ” : ” o b j e c t ” 549 } , 550 ”list_post_request_body” : { 551 ” example ” : [ 552 { 553 ”description” : ”Best series since 1990” , 554 ” id ” : 30 , 555 ” listname ” : ” top 10 s e r i e s ” , 556 ” category ” : ” s e r i e s ” , 557 ” tag ” : ” mystery ” , 558 ”date of release” : ”05/06/2010” 559 } , 560 { 561 ” a l l ” : true 562 } 563 ] , 564 ”properties” : { 565 ”description” : { 566 ” type ” : ” s t r i n g ” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 154

567 } , 568 ” id ” : { 569 ” format ” : ” i n t 32” , 570 ” type ” : ” i n t e g e r ” 571 } , 572 ” a l l ” : { 573 ” type ” : ” boolean ” 574 } , 575 ” listname ” : { 576 ” type ” : ” s t r i n g ” 577 } , 578 ” category ” : { 579 ” type ” : ” s t r i n g ” 580 } , 581 ” tag ” : { 582 ” type ” : ” s t r i n g ” 583 } , 584 ”date of release” : { 585 ” format ” : ” date ” , 586 ” type ” : ” s t r i n g ” 587 } 588 } , 589 ” type ” : ” o b j e c t ” 590 } , 591 ”administrator” : { 592 ” example ” : [ 593 { 594 ”admin name” : ”ADMIN01” , 595 ”admin id ” : 1 596 } 597 ] , 598 ”properties” : { 599 ”admin name” : { 600 ” type ” : ” s t r i n g ” 601 } , 602 ”admin id ” : { 603 ” format ” : ” i n t 32” , 604 ” type ” : ” i n t e g e r ” 605 } 606 } , 607 ” type ” : ” o b j e c t ” 608 } , 609 ”followlist” : { 610 ” example ” : [ 611 { 612 ” u s e r s ” : [ 613 1 , 614 5 , 615 7 , 616 12 , 617 10 Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 155

618 ] 619 } 620 ] , 621 ”properties” : { 622 ” u s e r s ” : { 623 ”maxItems” : 10000 , 624 ” items ” : { 625 ” format ” : ” i n t 32” , 626 ” type ” : ” i n t e g e r ” 627 } , 628 ” type ” : ” array ” 629 } 630 } , 631 ” type ” : ” o b j e c t ” 632 } , 633 ”search_get_default_response” : { 634 ” example ” : [ 635 { 636 ” username ” : ” Tasos ” , 637 ”date of birth” : ”04/05/1992” , 638 ” email ” : ”[email protected]” , 639 ” id ” : 250 640 } , 641 { 642 ” category ” : ” s e r i e s ” , 643 ” id ” : 30 , 644 ”description” : ”Best series since 1990” 645 } , 646 { 647 ” category ” : ” s e r i e s ” , 648 ” id ” : 30 , 649 ”date of release” : ”05/06/2010” , 650 ”description” : ”Best series since 1990” 651 } 652 ] , 653 ” r e q u i r e d ” : [ 654 ” id ” 655 ] , 656 ”properties” : { 657 ”description” : { 658 ” type ” : ” s t r i n g ” 659 } , 660 ” id ” : { 661 ” format ” : ” i n t 32” , 662 ” type ” : ” i n t e g e r ” 663 } , 664 ” email ” : { 665 ” type ” : ” s t r i n g ” 666 } , 667 ” category ” : { 668 ” type ” : ” s t r i n g ” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 156

669 } , 670 ” username ” : { 671 ” type ” : ” s t r i n g ” 672 } , 673 ”date of release” : { 674 ” format ” : ” date ” , 675 ” type ” : ” s t r i n g ” 676 } , 677 ”date of birth” : { 678 ” format ” : ” date ” , 679 ” type ” : ” s t r i n g ” 680 } 681 } , 682 ” type ” : ” o b j e c t ” 683 } , 684 ”admin_post_request_body” : { 685 ” r e q u i r e d ” : [ 686 ”administrator” 687 ] , 688 ”properties” : { 689 ”administrator” : { 690 ” $ r e f ” : ”#/definitions/administrator” 691 } 692 } , 693 ” type ” : ” o b j e c t ” 694 } , 695 ”user_put_request_body” : { 696 ” example ” : [ 697 { 698 ” l o c a t i o n ” : ”Sweden” , 699 ” username ” : ” Nick ” , 700 ” sex ” : ”Male” , 701 ” photo ” : ” http : //imgur .com/rand_photo” , 702 ”date of birth” : ”09 - 08 - 1002” 703 } , 704 { 705 ” trophy ” : ”trophytype” 706 } 707 ] , 708 ”properties” : { 709 ” l o c a t i o n ” : { 710 ” type ” : ” s t r i n g ” 711 } , 712 ” trophy ” : { 713 ” type ” : ” s t r i n g ” 714 } , 715 ” password ” : { 716 ” format ” : ” password ” , 717 ”minLength” : 8 , 718 ” type ” : ” s t r i n g ” 719 } , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 157

720 ” username ” : { 721 ” type ” : ” s t r i n g ” 722 } , 723 ” sex ” : { 724 ” type ” : ” s t r i n g ” 725 } , 726 ” photo ” : { 727 ” type ” : ” s t r i n g ” 728 } , 729 ”date of birth” : { 730 ” format ” : ” date ” , 731 ” type ” : ” s t r i n g ” 732 } 733 } , 734 ” type ” : ” o b j e c t ” 735 } , 736 ”search_get_ 200 _response ” : { 737 ” example ” : [ 738 { 739 ”sorted list” : [ 740 ”highest ratio listname” , 741 ”medium ratio listname” , 742 ”lowest ratio listname” 743 ] 744 } 745 ] , 746 ” r e q u i r e d ” : [ 747 ”sorted list” 748 ] , 749 ”properties” : { 750 ”sorted list” : { 751 ”maxItems” : 15 , 752 ” items ” : { 753 ” type ” : ” s t r i n g ” 754 } , 755 ” type ” : ” array ” 756 } 757 } , 758 ” type ” : ” o b j e c t ” 759 } , 760 ”list_get_default_response” : { 761 ”properties” : { 762 ”name” : { 763 ” type ” : ” s t r i n g ” 764 } 765 } , 766 ” type ” : ” o b j e c t ” 767 } , 768 ”comment” : { 769 ” example ” : [ 770 { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 158

771 ”comment id” : 12 , 772 ”comment content” : ”I like most of your list” 773 } 774 ] , 775 ”properties” : { 776 ”comment id” : { 777 ” format ” : ” i n t 32” , 778 ” type ” : ” i n t e g e r ” 779 } , 780 ”comment content” : { 781 ” type ” : ” s t r i n g ” 782 } 783 } , 784 ” type ” : ” o b j e c t ” 785 } , 786 ” r a t i n g ” : { 787 ” example ” : [ 788 { 789 ” r a t i o ” : 7 , 790 ” r a t i o id ” : 4 791 } 792 ] , 793 ”properties” : { 794 ” r a t i o ” : { 795 ” format ” : ” i n t 32” , 796 ” type ” : ” i n t e g e r ” 797 } , 798 ” r a t i o id ” : { 799 ” format ” : ” i n t 32” , 800 ” type ” : ” i n t e g e r ” 801 } 802 } , 803 ” type ” : ” o b j e c t ” 804 } , 805 ”rate_post_request_body” : { 806 ” r e q u i r e d ” : [ 807 ” r a t i n g ” 808 ] , 809 ”properties” : { 810 ” r a t i n g ” : { 811 ” $ r e f ” : ”#/definitions/rating” 812 } 813 } , 814 ” type ” : ” o b j e c t ” 815 } , 816 ”user_post_request_body” : { 817 ”properties” : { 818 ” user ” : { 819 ” $ r e f ” : ”#/definitions/user” 820 } 821 } , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 159

822 ” type ” : ” o b j e c t ” 823 } , 824 ”follow_list_post_request_body” : { 825 ” r e q u i r e d ” : [ 826 ”followlist” 827 ] , 828 ”properties” : { 829 ”followlist” : { 830 ” $ r e f ” : ”#/definitions/followlist” 831 } 832 } , 833 ” type ” : ” o b j e c t ” 834 } , 835 ” user ” : { 836 ” example ” : [ 837 { 838 ” id ” : 250 , 839 ” l o c a t i o n ” : ”Thessaloniki” , 840 ” s t a t u s ” : ” o n l i n e ” , 841 ” email ” : ”[email protected]” , 842 ” trophy ” : ”name” , 843 ” username ” : ” Tasos ” , 844 ” sex ” : ” male ” , 845 ” photo ” : ” http : //photo .com/myphoto” , 846 ”date of birth” : ”04/05/1992” 847 } 848 ] , 849 ”properties” : { 850 ” id ” : { 851 ” format ” : ” i n t 32” , 852 ” type ” : ” i n t e g e r ” 853 } , 854 ” l o c a t i o n ” : { 855 ” type ” : ” s t r i n g ” 856 } , 857 ” s t a t u s ” : { 858 ” type ” : ” s t r i n g ” 859 } , 860 ” email ” : { 861 ” type ” : ” s t r i n g ” 862 } , 863 ” trophy ” : { 864 ” type ” : ” s t r i n g ” 865 } , 866 ” password ” : { 867 ” format ” : ” password ” , 868 ” type ” : ” s t r i n g ” 869 } , 870 ” username ” : { 871 ” type ” : ” s t r i n g ” 872 } , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 160

873 ” sex ” : { 874 ” type ” : ” s t r i n g ” 875 } , 876 ” photo ” : { 877 ” type ” : ” s t r i n g ” 878 } , 879 ”date of birth” : { 880 ” format ” : ” date ” , 881 ” type ” : ” s t r i n g ” 882 } 883 } , 884 ” type ” : ” o b j e c t ” 885 } , 886 ”user_get_default_response” : { 887 ” example ” : [ 888 { 889 ” s t a t u s ” : ” i s o n l i n e ” , 890 ” username ” : ”Michalis Pap ” 891 } , 892 { 893 ” username ” : ” Tasos ” 894 } 895 ] , 896 ” r e q u i r e d ” : [ 897 ” username ” 898 ] , 899 ”properties” : { 900 ” s t a t u s ” : { 901 ” type ” : ” s t r i n g ” 902 } , 903 ” username ” : { 904 ” type ” : ” s t r i n g ” 905 } 906 } , 907 ” type ” : ” o b j e c t ” 908 } 909 } , 910 ” schemes ” : [ 911 ” https ” , 912 ” http ” 913 ] , 914 ” swagger ” : ”2 . 0” , 915 ” basePath ” : ”/v1” 916 }

C.2 Generic eshop

Παρακάτω παρατίθενται τα 5 resource files που γράφτηκαν με βάση την RDD μεθοδολογία. Στα resource files καταγράφονται οι απαιτήσεις του RESTful Web API ενός Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 161

υποθετικού ηλεκτρονικού καταστήματος. Επισημαίνεται ότι τα αρχεία παρατίθενται όπως χρησιμοποιήθηκαν στα πειράματα. Δηλαδή με σκοπό να αναδείξουν τις δυνατότητες του συστήματος που προτείνεται και όχι την λειτουργία του υποθετικού καταστήματος. Έτσι ό,τι περιγράφεται είναι ενδεικτικό και μπορεί να στερείτο νοήματος.

Παράδειγμα C.9: Eshop με RDD: product.resource Feature: product

# POST /product # GET, PUT, DELETE /product/{product_id}

Scenario: retrieve product When I retrieve a product by it`s id Then I should see the product as follows: | name | `Chair` | | description | `Made in Stockholm` | | color | `Deep dark brown` | | category | `furniture` | | on sale | false | | available in | 48 | # hours | shipping | `worldwide` | | doa | 7 | # days | id | 45 | | cost | 15000.1 | # € And I should be prompted to add it to the basket

Scenario: remove product from site Given I am logged in as administrator When I delete a product | name | `product` | | category | `furniture` | Then I should see the deleted product: | name | `Chair` | | description | `Made in Stockholm` | | color | `Deep dark brown` | | category | `furniture` | | on sale | false | | available in | 48 | # hours | shipping | `worldwide` | | doa | 7 | # days | id | 45 | | cost | 15000.1 | # €

Scenario: add product to site Given I am logged in as administrator When I add a new product: | name | `Chair` | | description | `Made in Stockholm` | | color | `Deep dark brown` | | category | `furniture` | | on sale | false | | available in | 48 | # hours | shipping | `worldwide` | | doa | 7 | # days | id | 45 | | cost | 15000.1 | # € Then I should see the created product: Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 162

| name | `Chair` | | description | `Made in Stockholm` | | color | `Deep dark brown` | | category | `furniture` | | on sale | false | | available in | 48 | # hours | shipping | `worldwide` | | doa | 7 | # days | id | 45 | | cost | 15000.1 | # €

Scenario: update product # Given an existing product Given that I am logged in as administrator When I update the product: | name | `bag` | | description | `great bag` | | category | `sports` | And I specify it`s description Then I should see the updated product | name | `bag` | | description | `small bag` | | category | `sports` |

Scenario: product doesn`t exist Given that a product doesn`t exist When I try to delete, retrieve or edit the product Then I should see a message telling me "the product doesn`t exist"

Scenario: not logged in Given that I`m not logged in When I try to add, delete or update a product Then I should see a message telling me "Not allowed"

Παράδειγμα C.10: Eshop με RDD: search.resource Feature: Search products

# GET /search?n={product_name}&c={category_name}

Scenario: Search for a product The user is able to search for products in the website using name and/or category filter, view their general details and choose to view their specific details When I search for a product by it`s name and/or it`s category | name | `keyboard` | | category | `electronics` | Then a list of relevant products appears with the following format | name | price | | `keyboard` | 69.99 | #€ And I have the option to view a product

Παράδειγμα C.11: Eshop με RDD: basket.resource Feature: basket

# POST /basket Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 163

# GET, PUT /basket/{basket_id}

Scenario: new basket When I submit a basket: | product ids | [14556,14777,12001,12451] | maximum of 100 | | quantities | [1,1,1,2] | maximum of 100 | Then I should see | product ids | [14556,14777,12001,12451] | maximum of 100 | | quantities | [1,1,1,2] | maximum of 100 | | basket id | 1 | | And I should be prompted to create an order And I should have the option to view my basket

Scenario: update basket Given I have a basket with products When I update the basket by it`s id And I submit new product in this format | product id | 14777 | | quantity | 3 | Then I should see | product ids | [14777] | | quantity | 4 | And I should be prompted to create an order And I should have the option to view my basket

Scenario: retrieve basket Given I have a basket with products When I retrieve the basket by it`s id Then I should see a basket: | product ids | [14556,14777,12001,12451] | maximum of 100 | | quantities | [1,1,1,2] | maximum of 100 | | basket id | 1 | | And I should be prompted to create an order And I should have the option to view my basket

Παράδειγμα C.12: Eshop με RDD: order.resource Feature: order products

# POST /order # GET, PUT, DELETE /order/{order_id}

Scenario: submit new order # Given that I have a basket with products When I submit an order |order document|file| Then I should see the message "Order created successfully" And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Scenario: cancel submitted order # Given I have ordered When I cancel the order Then I should see a success message saying "Order canceled" And I should be prompted to request a search Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 164

Scenario: update unpaid order # Given I have ordered # And the order status is "unpaid" When I update an order by it`s id And I specify the following basket | product ids | [3433,1212,1276] | | | quantities | [1,1,1,2] | maximum of 100 | Then I should see a success message saying "Order updated" And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Scenario: view unpaid order Given that I have ordered When I request an order by it`s id Then I can view the details of the order | product names | [`Chair`,`Keyboard`,`Dell Laptop`] | | product descriptions | [`Made in Stockholm`,`Mechanical`,\ `IPS Screen`] | And I should be prompted to submit a payment And I have the option to review the order And I have the option to cancel the order And I have the option to update the order

Scenario: order doesn`t exist Given an order doesn`t exist When I request, delete or update that order Then I should see a message "That order doesn`t exist"

Παράδειγμα C.13: Eshop με RDD: payment.resource Feature: pay for order

# POST /order/{order_id}/payment

Background: Given the id of an unpaid order

Scenario: pay for order Possible payment options are `credit`, `cash`, `paypal` When I submit a payment for an order | amount | 28.2 | | date | 8/2/2017 12:32 | | type | `credit` | Then I should be prompted to view the order

Scenario: pay for order less or more money When I submit a wrong payment for an order Then I should see a message saying "wrong amount" And I should be prompted to submit a payment And I should be prompted to view the order

Παράδειγμα C.14: Eshop με RDD: pending deliveries.resource Feature: Check the products pending for delivery

Scenario: view delivery Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 165

# Given that I have ordered When I request a delivery by it`s id Then I can view the details of the order | product names | [`Chair`,`Keyboard`,`Dell Laptop`] | | product descriptions | [`Made in Stockholm`,`Mechanical`,\ `IPS Screen`] | And I have the option to review the pending deliveries Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 166

OpenAPI Specification

Παράδειγμα C.15: Eshop με RDD: OpenAPI Specification 1 { 2 ” produces ” : [ 3 ”application/json” 4 ] , 5 ” host ” : ”localhost” , 6 ”definitions” : { 7 ”order_delete_ 200 _response ” : { 8 ”x - l i n k s ” : [ 9 { 10 ” path ” : ”/ search ” , 11 ”operation” : ” get ” 12 } 13 ] , 14 ” type ” : ” o b j e c t ” 15 } , 16 ”order_post_ 200 _response ” : { 17 ”x - l i n k s ” : [ 18 { 19 ” path ” : ”/ order /{ order_id }/payment” , 20 ”operation” : ” post ” 21 } , 22 { 23 ” path ” : ”/ order /{ order_id }” , 24 ”operation” : ” get ” 25 } , 26 { 27 ” path ” : ”/ order /{ order_id }” , 28 ”operation” : ” d e l e t e ” 29 } , 30 { 31 ” path ” : ”/ order /{ order_id }” , 32 ”operation” : ” put ” 33 } 34 ] , 35 ” type ” : ” o b j e c t ” 36 } , 37 ” basket ” : { 38 ” example ” : [ 39 { 40 ” basket id ” : 1 , 41 ”product ids” : [ 42 14556 , 43 14777 , 44 12001 , 45 12451 46 ] , 47 ”quantities” : [ 48 1 , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 167

49 1 , 50 1 , 51 2 52 ] 53 } 54 ] , 55 ”properties” : { 56 ” basket id ” : { 57 ” format ” : ” i n t 32” , 58 ” type ” : ” i n t e g e r ” 59 } , 60 ”product ids” : { 61 ” items ” : { 62 ” format ” : ” i n t 32” , 63 ” type ” : ” i n t e g e r ” 64 } , 65 ”maxItems” : 100 , 66 ” type ” : ” array ” 67 } , 68 ”quantities” : { 69 ” items ” : { 70 ” format ” : ” i n t 32” , 71 ” type ” : ” i n t e g e r ” 72 } , 73 ”maxItems” : 100 , 74 ” type ” : ” array ” 75 } 76 } , 77 ” type ” : ” o b j e c t ” 78 } , 79 ”basket_post_request_body” : { 80 ” r e q u i r e d ” : [ 81 ” basket ” 82 ] , 83 ”properties” : { 84 ” basket ” : { 85 ” $ r e f ” : ”#/definitions/basket” 86 } 87 } , 88 ” type ” : ” o b j e c t ” 89 } , 90 ”search_get_default_response” : { 91 ” r e q u i r e d ” : [ 92 ”name” , 93 ” p r i c e ” 94 ] , 95 ”properties” : { 96 ”name” : { 97 ” type ” : ” s t r i n g ” 98 } , 99 ” p r i c e ” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 168

100 ” format ” : ” f l o a t ” , 101 ” type ” : ”number” 102 } 103 } , 104 ”x - l i n k s ” : [ 105 { 106 ” path ” : ”/ product /{ product_id }” , 107 ”operation” : ” get ” 108 } 109 ] , 110 ” type ” : ” o b j e c t ” , 111 ” example ” : [ 112 { 113 ”name” : ” keyboard ” , 114 ” p r i c e ” : 69 . 99 115 } 116 ] 117 } , 118 ”basket_put_default_response” : { 119 ” r e q u i r e d ” : [ 120 ”product ids” , 121 ” quantity ” 122 ] , 123 ”properties” : { 124 ” quantity ” : { 125 ” format ” : ” i n t 32” , 126 ” type ” : ” i n t e g e r ” 127 } , 128 ”product ids” : { 129 ” items ” : { 130 ” format ” : ” i n t 32” , 131 ” type ” : ” i n t e g e r ” 132 } , 133 ” type ” : ” array ” 134 } 135 } , 136 ”x - l i n k s ” : [ 137 { 138 ” path ” : ”/ order ” , 139 ”operation” : ” post ” 140 } , 141 { 142 ” path ” : ”/ basket /{ basket_id }” , 143 ”operation” : ” get ” 144 } 145 ] , 146 ” type ” : ” o b j e c t ” , 147 ” example ” : [ 148 { 149 ” quantity ” : 4 , 150 ”product ids” : [ Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 169

151 1 , 152 4 , 153 7 , 154 7 , 155 7 156 ] 157 } 158 ] 159 } , 160 ”payment_post_default_response” : { 161 ”x - l i n k s ” : [ 162 { 163 ” path ” : ”/ order /{ order_id }” , 164 ”operation” : ” get ” 165 } 166 ] , 167 ” type ” : ” o b j e c t ” 168 } , 169 ”order_get_default_response” : { 170 ” r e q u i r e d ” : [ 171 ”product names” , 172 ”product descriptions” 173 ] , 174 ”properties” : { 175 ”product descriptions” : { 176 ” items ” : { 177 ” type ” : ” s t r i n g ” 178 } , 179 ” type ” : ” array ” 180 } , 181 ”product names” : { 182 ” items ” : { 183 ” type ” : ” s t r i n g ” 184 } , 185 ” type ” : ” array ” 186 } 187 } , 188 ”x - l i n k s ” : [ 189 { 190 ” path ” : ”/ order /{ order_id }/payment” , 191 ”operation” : ” post ” 192 } , 193 { 194 ” path ” : ”/ order /{ order_id }” , 195 ”operation” : ” get ” 196 } , 197 { 198 ” path ” : ”/ order /{ order_id }” , 199 ”operation” : ” d e l e t e ” 200 } , 201 { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 170

202 ” path ” : ”/ order /{ order_id }” , 203 ”operation” : ” put ” 204 } 205 ] , 206 ” type ” : ” o b j e c t ” , 207 ” example ” : [ 208 { 209 ”product descriptions” : [ 210 ”Made in Stockholm” , 211 ”Mechanical” , 212 ”IPS Screen” 213 ] , 214 ”product names” : [ 215 ” Chair ” , 216 ”Keyboard” , 217 ”Dell Laptop” 218 ] 219 } 220 ] 221 } , 222 ”product_get_default_response” : { 223 ” r e q u i r e d ” : [ 224 ” product ” 225 ] , 226 ”properties” : { 227 ” product ” : { 228 ” $ r e f ” : ”#/definitions/product” 229 } 230 } , 231 ”x - l i n k s ” : [ 232 { 233 ” path ” : ”/ basket ” , 234 ”operation” : ” post ” 235 } 236 ] , 237 ” type ” : ” o b j e c t ” 238 } , 239 ”pending_deliveries_get_default_response” : { 240 ” r e q u i r e d ” : [ 241 ”product names” , 242 ”product descriptions” 243 ] , 244 ”properties” : { 245 ”product descriptions” : { 246 ” items ” : { 247 ” type ” : ” s t r i n g ” 248 } , 249 ” type ” : ” array ” 250 } , 251 ”product names” : { 252 ” items ” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 171

253 ” type ” : ” s t r i n g ” 254 } , 255 ” type ” : ” array ” 256 } 257 } , 258 ”x - l i n k s ” : [ 259 { 260 ” path ” : ”/pending_deliveries” , 261 ”operation” : ” get ” 262 } 263 ] , 264 ” type ” : ” o b j e c t ” , 265 ” example ” : [ 266 { 267 ”product descriptions” : [ 268 ”Made in Stockholm” , 269 ”Mechanical” , 270 ”IPS Screen” 271 ] , 272 ”product names” : [ 273 ” Chair ” , 274 ”Keyboard” , 275 ”Dell Laptop” 276 ] 277 } 278 ] 279 } , 280 ”basket_put_request_body” : { 281 ” r e q u i r e d ” : [ 282 ”product id” , 283 ” quantity ” 284 ] , 285 ”properties” : { 286 ” quantity ” : { 287 ” format ” : ” i n t 32” , 288 ” type ” : ” i n t e g e r ” 289 } , 290 ”product id” : { 291 ” format ” : ” i n t 32” , 292 ” type ” : ” i n t e g e r ” 293 } 294 } , 295 ” type ” : ” o b j e c t ” , 296 ” example ” : [ 297 { 298 ” quantity ” : 3 , 299 ”product id” : 14777 300 } 301 ] 302 } , 303 ”product_delete_default_response” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 172

304 ” r e q u i r e d ” : [ 305 ” product ” 306 ] , 307 ”properties” : { 308 ” product ” : { 309 ” $ r e f ” : ”#/definitions/product” 310 } 311 } , 312 ” type ” : ” o b j e c t ” 313 } , 314 ” product ” : { 315 ” example ” : [ 316 { 317 ” c o s t ” : 15000 . 1 , 318 ” id ” : 45 , 319 ” c o l o r ” : ”Deep dark brown” , 320 ”on s a l e ” : f a l s e , 321 ”available in” : 48 , 322 ”description” : ”Made in Stockholm” , 323 ”name” : ” Chair ” , 324 ” category ” : ”furniture” , 325 ” shipping ” : ”worldwide” , 326 ”doa” : 7 327 } 328 ] , 329 ”properties” : { 330 ”doa” : { 331 ” format ” : ” i n t 32” , 332 ” type ” : ” i n t e g e r ” 333 } , 334 ” c o s t ” : { 335 ” format ” : ” f l o a t ” , 336 ” type ” : ”number” 337 } , 338 ” c o l o r ” : { 339 ” type ” : ” s t r i n g ” 340 } , 341 ” shipping ” : { 342 ” type ” : ” s t r i n g ” 343 } , 344 ” id ” : { 345 ” format ” : ” i n t 32” , 346 ” type ” : ” i n t e g e r ” 347 } , 348 ”available in” : { 349 ” format ” : ” i n t 32” , 350 ” type ” : ” i n t e g e r ” 351 } , 352 ”description” : { 353 ” type ” : ” s t r i n g ” 354 } , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 173

355 ”name” : { 356 ” type ” : ” s t r i n g ” 357 } , 358 ” category ” : { 359 ” type ” : ” s t r i n g ” 360 } , 361 ”on s a l e ” : { 362 ” type ” : ” boolean ” 363 } 364 } , 365 ” type ” : ” o b j e c t ” 366 } , 367 ”payment_post_400 _response ” : { 368 ”x - l i n k s ” : [ 369 { 370 ” path ” : ”/ order /{ order_id }/payment” , 371 ”operation” : ” post ” 372 } , 373 { 374 ” path ” : ”/ order /{ order_id }” , 375 ”operation” : ” get ” 376 } 377 ] , 378 ” type ” : ” o b j e c t ” 379 } , 380 ”product_post_default_response” : { 381 ” r e q u i r e d ” : [ 382 ” product ” 383 ] , 384 ”properties” : { 385 ” product ” : { 386 ” $ r e f ” : ”#/definitions/product” 387 } 388 } , 389 ” type ” : ” o b j e c t ” 390 } , 391 ”basket_post_default_response” : { 392 ” r e q u i r e d ” : [ 393 ”product ids” , 394 ”quantities” , 395 ” basket id ” 396 ] , 397 ”properties” : { 398 ” basket id ” : { 399 ” format ” : ” i n t 32” , 400 ” type ” : ” i n t e g e r ” 401 } , 402 ”product ids” : { 403 ” items ” : { 404 ” format ” : ” i n t 32” , 405 ” type ” : ” i n t e g e r ” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 174

406 } , 407 ”maxItems” : 100 , 408 ” type ” : ” array ” 409 } , 410 ”quantities” : { 411 ” items ” : { 412 ” format ” : ” i n t 32” , 413 ” type ” : ” i n t e g e r ” 414 } , 415 ”maxItems” : 100 , 416 ” type ” : ” array ” 417 } 418 } , 419 ”x - l i n k s ” : [ 420 { 421 ” path ” : ”/ order ” , 422 ”operation” : ” post ” 423 } , 424 { 425 ” path ” : ”/ basket /{ basket_id }” , 426 ”operation” : ” get ” 427 } 428 ] , 429 ” type ” : ” o b j e c t ” , 430 ” example ” : [ 431 { 432 ” basket id ” : 1 , 433 ”product ids” : [ 434 14556 , 435 14777 , 436 12001 , 437 12451 438 ] , 439 ”quantities” : [ 440 1 , 441 1 , 442 1 , 443 2 444 ] 445 } 446 ] 447 } , 448 ”product_put_default_response” : { 449 ” r e q u i r e d ” : [ 450 ”name” , 451 ”description” , 452 ” category ” 453 ] , 454 ”properties” : { 455 ”description” : { 456 ” type ” : ” s t r i n g ” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 175

457 } , 458 ”name” : { 459 ” type ” : ” s t r i n g ” 460 } , 461 ” category ” : { 462 ” type ” : ” s t r i n g ” 463 } 464 } , 465 ” type ” : ” o b j e c t ” , 466 ” example ” : [ 467 { 468 ”description” : ” small bag” , 469 ”name” : ”bag” , 470 ” category ” : ” s p o r t s ” 471 } 472 ] 473 } , 474 ”payment_post_request_body” : { 475 ” example ” : [ 476 { 477 ” date ” : ”8/2/2017 12 : 32” , 478 ”amount” : 28 . 2 , 479 ” type ” : ” c r e d i t ” 480 } 481 ] , 482 ”properties” : { 483 ” date ” : { 484 ” format ” : ”date -time” , 485 ” type ” : ” s t r i n g ” 486 } , 487 ”amount” : { 488 ” format ” : ” f l o a t ” , 489 ” type ” : ”number” 490 } , 491 ” type ” : { 492 ” type ” : ” s t r i n g ” 493 } 494 } , 495 ” type ” : ” o b j e c t ” 496 } , 497 ”order_put_200 _response ” : { 498 ”x - l i n k s ” : [ 499 { 500 ” path ” : ”/ order /{ order_id }/payment” , 501 ”operation” : ” post ” 502 } , 503 { 504 ” path ” : ”/ order /{ order_id }” , 505 ”operation” : ” get ” 506 } , 507 { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 176

508 ” path ” : ”/ order /{ order_id }” , 509 ”operation” : ” d e l e t e ” 510 } , 511 { 512 ” path ” : ”/ order /{ order_id }” , 513 ”operation” : ” put ” 514 } 515 ] , 516 ” type ” : ” o b j e c t ” 517 } , 518 ”product_put_request_body” : { 519 ”properties” : { 520 ”description” : { 521 ” type ” : ” s t r i n g ” 522 } , 523 ” product ” : { 524 ” $ r e f ” : ”#/definitions/product” 525 } 526 } , 527 ” type ” : ” o b j e c t ” 528 } , 529 ”basket_get_default_response” : { 530 ” r e q u i r e d ” : [ 531 ” basket ” 532 ] , 533 ”properties” : { 534 ” basket ” : { 535 ” $ r e f ” : ”#/definitions/basket” 536 } 537 } , 538 ”x - l i n k s ” : [ 539 { 540 ” path ” : ”/ order ” , 541 ”operation” : ” post ” 542 } , 543 { 544 ” path ” : ”/ basket /{ basket_id }” , 545 ”operation” : ” get ” 546 } 547 ] , 548 ” type ” : ” o b j e c t ” 549 } , 550 ”order_put_request_body” : { 551 ” r e q u i r e d ” : [ 552 ”product ids” , 553 ”quantities” 554 ] , 555 ”properties” : { 556 ”product ids” : { 557 ” items ” : { 558 ” format ” : ” i n t 32” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 177

559 ” type ” : ” i n t e g e r ” 560 } , 561 ” type ” : ” array ” 562 } , 563 ”quantities” : { 564 ” items ” : { 565 ” format ” : ” i n t 32” , 566 ” type ” : ” i n t e g e r ” 567 } , 568 ”maxItems” : 100 , 569 ” type ” : ” array ” 570 } 571 } , 572 ” type ” : ” o b j e c t ” , 573 ” example ” : [ 574 { 575 ”product ids” : [ 576 3433 , 577 1212 , 578 1276 579 ] , 580 ”quantities” : [ 581 1 , 582 1 , 583 1 , 584 2 585 ] 586 } 587 ] 588 } , 589 ”product_post_request_body” : { 590 ”properties” : { 591 ” product ” : { 592 ” $ r e f ” : ”#/definitions/product” 593 } 594 } , 595 ” type ” : ” o b j e c t ” 596 } 597 } , 598 ”securityDefinitions” : { 599 ”administrator” : { 600 ” scopes ” : { 601 ” put : / product ” : ”No description” , 602 ” post : / product ” : ”No description” , 603 ” d e l e t e : / product ” : ”No description” 604 } , 605 ”authorizationUrl” : ” http : //swagger. io/api/oauth/dialog ” , 606 ” type ” : ” oauth 2” , 607 ” flow ” : ” i m p l i c i t ” 608 } Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 178

609 } , 610 ” basePath ” : ”/v1” , 611 ” schemes ” : [ 612 ” https ” , 613 ” http ” 614 ] , 615 ” paths ” : { 616 ”/ basket /{ basket_id }” : { 617 ” get ” : { 618 ”responses” : { 619 ” d e f a u l t ” : { 620 ”description” : ”None” , 621 ”schema” : { 622 ” $ r e f ” : ”#/ d e f i n i t i o n s / basket_get_default_response” 623 } 624 } 625 } , 626 ”parameters” : [ 627 { 628 ” r e q u i r e d ” : true , 629 ”name” : ”basket_id” , 630 ” format ” : ” i n t 32” , 631 ” type ” : ” i n t e g e r ” , 632 ” in ” : ” path ” 633 } 634 ] 635 } , 636 ” put ” : { 637 ”responses” : { 638 ” d e f a u l t ” : { 639 ”description” : ”None” , 640 ”schema” : { 641 ” $ r e f ” : ”#/ d e f i n i t i o n s / basket_put_default_response” 642 } 643 } 644 } , 645 ”parameters” : [ 646 { 647 ”schema” : { 648 ” $ r e f ” : ”#/ d e f i n i t i o n s / basket_put_request_body” 649 } , 650 ”name” : ”basket_put_request_body” , 651 ” in ” : ”body” 652 } , 653 { 654 ” r e q u i r e d ” : true , 655 ”name” : ”basket_id” , 656 ” format ” : ” i n t 32” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 179

657 ” type ” : ” i n t e g e r ” , 658 ” in ” : ” path ” 659 } 660 ] 661 } 662 } , 663 ”/ product /{ product_id }” : { 664 ” get ” : { 665 ”responses” : { 666 ”404” : { 667 ”description” : ”the product doesn’t exist” 668 } , 669 ” d e f a u l t ” : { 670 ”description” : ”None” , 671 ”schema” : { 672 ” $ r e f ” : ”#/ d e f i n i t i o n s / product_get_default_response” 673 } 674 } 675 } , 676 ”parameters” : [ 677 { 678 ” r e q u i r e d ” : true , 679 ”name” : ”product_id” , 680 ” format ” : ” i n t 32” , 681 ” type ” : ” i n t e g e r ” , 682 ” in ” : ” path ” 683 } 684 ] 685 } 686 } , 687 ”/ order /{ order_id }/payment” : { 688 ” post ” : { 689 ”description” : ”- \tPossible payment options are ’ c r e d i t ’ , ’ cash ’ , ’ paypal ’ ” , 690 ”responses” : { 691 ”400” : { 692 ”description” : ”wrong amount” , 693 ”schema” : { 694 ” $ r e f ” : ”#/definitions/payment_post_400 _response ” 695 } 696 } , 697 ” d e f a u l t ” : { 698 ”description” : ”None” , 699 ”schema” : { 700 ” $ r e f ” : ”#/ d e f i n i t i o n s / payment_post_default_response” 701 } 702 } 703 } , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 180

704 ”parameters” : [ 705 { 706 ”schema” : { 707 ” $ r e f ” : ”#/ d e f i n i t i o n s / payment_post_request_body” 708 } , 709 ”name” : ”payment_post_request_body” , 710 ” in ” : ”body” 711 } , 712 { 713 ” r e q u i r e d ” : true , 714 ”name” : ” order_id ” , 715 ” format ” : ” i n t 32” , 716 ” type ” : ” i n t e g e r ” , 717 ” in ” : ” path ” 718 } 719 ] 720 } 721 } , 722 ”/pending_deliveries” : { 723 ” get ” : { 724 ”responses” : { 725 ” d e f a u l t ” : { 726 ”description” : ”None” , 727 ”schema” : { 728 ” $ r e f ” : ”#/ d e f i n i t i o n s / pending_deliveries_get_default_response ” 729 } 730 } 731 } , 732 ”parameters” : [ 733 { 734 ” r e q u i r e d ” : true , 735 ”name” : ” d e l i v e r y ” , 736 ” in ” : ” query ” , 737 ” type ” : ” s t r i n g ” 738 } , 739 { 740 ” format ” : ” i n t 32” , 741 ” r e q u i r e d ” : true , 742 ”name” : ” id ” , 743 ” in ” : ” query ” , 744 ” type ” : ” i n t e g e r ” 745 } 746 ] 747 } 748 } , 749 ”/ product ” : { 750 ” d e l e t e ” : { 751 ”responses” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 181

752 ”404” : { 753 ”description” : ”the product doesn’t exist” 754 } , 755 ” d e f a u l t ” : { 756 ”description” : ”None” , 757 ”schema” : { 758 ” $ r e f ” : ”#/ d e f i n i t i o n s / product_delete_default_response” 759 } 760 } 761 } , 762 ”parameters” : [ 763 { 764 ” r e q u i r e d ” : f a l s e , 765 ”name” : ”name” , 766 ” in ” : ” query ” , 767 ” type ” : ” s t r i n g ” 768 } , 769 { 770 ” r e q u i r e d ” : f a l s e , 771 ”name” : ” category ” , 772 ” in ” : ” query ” , 773 ” type ” : ” s t r i n g ” 774 } 775 ] , 776 ” s e c u r i t y ” : [ 777 { 778 ”administrator” : [ 779 ” d e l e t e : / product ” 780 ] 781 } 782 ] 783 } , 784 ” post ” : { 785 ”responses” : { 786 ”404” : { 787 ”description” : ”Not allowed” 788 } , 789 ” d e f a u l t ” : { 790 ”description” : ”None” , 791 ”schema” : { 792 ” $ r e f ” : ”#/ d e f i n i t i o n s / product_post_default_response” 793 } 794 } 795 } , 796 ”parameters” : [ 797 { 798 ”schema” : { 799 ” $ r e f ” : ”#/ d e f i n i t i o n s / product_post_request_body” Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 182

800 } , 801 ”name” : ”product_post_request_body” , 802 ” in ” : ”body” 803 } 804 ] , 805 ” s e c u r i t y ” : [ 806 { 807 ”administrator” : [ 808 ” post : / product ” 809 ] 810 } 811 ] 812 } , 813 ” put ” : { 814 ”responses” : { 815 ”404” : { 816 ”description” : ”the product doesn’t exist” 817 } , 818 ” d e f a u l t ” : { 819 ”description” : ”None” , 820 ”schema” : { 821 ” $ r e f ” : ”#/ d e f i n i t i o n s / product_put_default_response” 822 } 823 } 824 } , 825 ”parameters” : [ 826 { 827 ”schema” : { 828 ” $ r e f ” : ”#/ d e f i n i t i o n s / product_put_request_body” 829 } , 830 ”name” : ”product_put_request_body” , 831 ” in ” : ”body” 832 } 833 ] , 834 ” s e c u r i t y ” : [ 835 { 836 ”administrator” : [ 837 ” put : / product ” 838 ] 839 } 840 ] 841 } 842 } , 843 ”/ order ” : { 844 ” post ” : { 845 ” consumes ” : [ 846 ”multipart/form-data” , 847 ”application/x-www-form-urlencoded” 848 ] , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 183

849 ”responses” : { 850 ”200” : { 851 ”description” : ”Order created successfully” , 852 ”schema” : { 853 ” $ r e f ” : ”#/definitions/order_post_ 200 _response ” 854 } 855 } 856 } , 857 ”parameters” : [ 858 { 859 ” r e q u i r e d ” : true , 860 ”name” : ”order document” , 861 ” in ” : ” formData ” , 862 ” type ” : ” f i l e ” 863 } 864 ] 865 } 866 } , 867 ”/ basket ” : { 868 ” post ” : { 869 ”responses” : { 870 ” d e f a u l t ” : { 871 ”description” : ”None” , 872 ”schema” : { 873 ” $ r e f ” : ”#/ d e f i n i t i o n s / basket_post_default_response” 874 } 875 } 876 } , 877 ”parameters” : [ 878 { 879 ” r e q u i r e d ” : true , 880 ”schema” : { 881 ” $ r e f ” : ”#/ d e f i n i t i o n s / basket_post_request_body” 882 } , 883 ”name” : ”basket_post_request_body” , 884 ” in ” : ”body” 885 } 886 ] 887 } 888 } , 889 ”/ order /{ order_id }” : { 890 ” d e l e t e ” : { 891 ”responses” : { 892 ”200” : { 893 ”description” : ”Order canceled” , 894 ”schema” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 184

895 ” $ r e f ” : ”#/definitions/order_delete_ 200 _response ” 896 } 897 } 898 } , 899 ”parameters” : [ 900 { 901 ” r e q u i r e d ” : true , 902 ”name” : ” order_id ” , 903 ” format ” : ” i n t 32” , 904 ” type ” : ” i n t e g e r ” , 905 ” in ” : ” path ” 906 } 907 ] 908 } , 909 ” get ” : { 910 ”responses” : { 911 ”404” : { 912 ”description” : ”That order doesn’t exist” 913 } , 914 ” d e f a u l t ” : { 915 ”description” : ”None” , 916 ”schema” : { 917 ” $ r e f ” : ”#/ d e f i n i t i o n s / order_get_default_response” 918 } 919 } 920 } , 921 ”parameters” : [ 922 { 923 ” r e q u i r e d ” : true , 924 ”name” : ” order_id ” , 925 ” format ” : ” i n t 32” , 926 ” type ” : ” i n t e g e r ” , 927 ” in ” : ” path ” 928 } 929 ] 930 } , 931 ” put ” : { 932 ”responses” : { 933 ”200” : { 934 ”description” : ”Order updated” , 935 ”schema” : { 936 ” $ r e f ” : ”#/definitions/order_put_200 _response ” 937 } 938 } 939 } , 940 ”parameters” : [ 941 { 942 ”schema” : { Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 185

943 ” $ r e f ” : ”#/ d e f i n i t i o n s / order_put_request_body” 944 } , 945 ”name” : ”order_put_request_body” , 946 ” in ” : ”body” 947 } , 948 { 949 ” r e q u i r e d ” : true , 950 ”name” : ” order_id ” , 951 ” format ” : ” i n t 32” , 952 ” type ” : ” i n t e g e r ” , 953 ” in ” : ” path ” 954 } 955 ] 956 } 957 } , 958 ”/ search ” : { 959 ” get ” : { 960 ”description” : ”- \tThe user is able to search for products in the website using name and/or category filter , view their general details and choose to view their\n\tspecific details” , 961 ”responses” : { 962 ” d e f a u l t ” : { 963 ”description” : ”None” , 964 ”schema” : { 965 ” $ r e f ” : ”#/ d e f i n i t i o n s / search_get_default_response” 966 } 967 } 968 } , 969 ”parameters” : [ 970 { 971 ” r e q u i r e d ” : true , 972 ”name” : ”name” , 973 ” in ” : ” query ” , 974 ” type ” : ” s t r i n g ” 975 } , 976 { 977 ” r e q u i r e d ” : true , 978 ”name” : ” category ” , 979 ” in ” : ” query ” , 980 ” type ” : ” s t r i n g ” 981 } 982 ] 983 } 984 } 985 } , 986 ” swagger ” : ”2 . 0” , 987 ” i n f o ” : { 988 ” t i t l e ” : ”Generic eshop” , Παράρτημα C. Απαιτήσεις API κατά RDD & OpenAPI Specifications 186

989 ” contact ” : { 990 ”name” : ” Tasos ” , 991 ” u r l ” : ”” , 992 ” email ” : ”[email protected]” 993 } , 994 ” v e r s i o n ” : ”1” , 995 ”description” : ”Diploma Thesis” , 996 ”termsOfService” : ”” , 997 ” l i c e n s e ” : { 998 ”name” : ”” , 999 ” u r l ” : ”” 1000 } 1001 } 1002 } 187 Παράρτημα D

Gherkin Specifications Document

Writing requirements in Gherkin based on Web resources This document describes the writing style of Gherkin files, as part of the Resource Driven Development methodology introduced by the Gherkin2OAS tool. Requirements are written in files. As in, usual -operating system- electronic files. All files are regular text files. The extension of the file must be “.resource”. The file name must be the same as the resource it describes. The files can be organized in any number of folders, including subfolders and so on. Each file describes only one resource. The files begin with the “Feature” keyword. The contents of the “Feature” keyword can be anything. Under the “Feature” keyword, “Background” and “Scenario” sections can be added. While the “Background” section is optional, there must be at least one “Scenario” section. In the file, the functionality of the API that uses the resource, is described, with natural language. More specifically:

Under the “Background” section, API roles and resource relations can be described. Backgrounds are written in a Given..And type of block. The API roles that are described here will have access to all the operations described in the scenarios below. Regarding the resource relations: Each resource will end up having a path in the API. The path will consist of a seed, a resource identification parameter (if any) and a hierarchy (if any). The seed comes from the name of the resource. The identification is always to the right of the seed (as the path is seen visually in text) and comes from the scenarios. The resource hierarchy is always to the left of the seed and comes from this section. So when other resources are described as relations in the “Background” section, keep in mind that they will always be treated as higher hierarchy resources. As a result they will be placed to the left of the path. If you want to describe a lower hierarchy resource, you should go to that lower hierarchy resource file and describe it’s higher hierarchy there instead.

Under each “Scenario” section, one or more API operations can be described. Sce- narios are written in a Given..When..Then type of block. Under each Given,When,Then keyword extra steps can be added with the And keyword. • In the ”Given” part of the scenario, roles can be described. The authorization of the roles described will only apply to the current scenario. • In the ”When” part of the scenario, the action of the application to the API is de- scribed. The action must be one of Create, Read, Update, Delete resource. If it’s not Create, Gherkin2OAS will try to figure out the path parameter for resource identification. If not specified, an id will be assumed. Nouns here are in general treated as string parameters. If you want to specify the data type of your parame- ters, you must put them in a Gherkin Data Table. In one column/row the names of Παράρτημα D. Gherkin Specifications Document 188

the parameters are listed and in the other a representative example i.e. if your data type is float, don’t type as an example “5” but “5.1”. The data types supported are OpenApi Specification data types1. Specifically the types ’string’, ’integer’, ’num- ber’, ’file’, ’date’, ’date-time’, ’boolean’, ’password’, ’array’ and ’file’. Arrays must be declared with [brackets]. Array items can be seperated with commas, spaces, tabs and pipes. Finally the type ’file’ is supported only in the ’When’ step. In that case, the request must have no other parameters. If more than one operations are described in the When part, they will all have the same parameters and responses. • In the ”Then” part of the scenario the response from the API to the applica- tion is described. This includes status code messages, parameters and links to other resources. For parameters the same rules apply as for When. For sta- tus code messages, the message should be in quoted text. Right now the codes 200,201,202,400,401 and 404 are supported. For links to other resources, the name of the resource and the operation applied to it must be mentioned in the sentence. General note: Keep your sentences simple. Use the And keyword to avoid long sen- tences. Please read the files in the examples to better understand the usage of the specification.

1https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types 189 Βιβλιογραφία

[1] Acceptance/Customer Tests as Requirements Artifacts: An Agile Introduction. url: http://agilemodeling.com/artifacts/acceptanceTests.htm. [2] Kent Beck. Test Driven Development: By Example. Addison-Wesley Longman, 2002. 137 pp. isbn: 978-0321146533. url: http://www.eecs.yorku.ca/course_archive/ 2003-04/W/3311/sectionM/case_studies/money/KentBeck_TDD_byexample.pdf. [3] Cloud Computing. url: https://en.wikipedia.org/wiki/Cloud_computing. [4] Cloud Storage. url: https://en.wikipedia.org/wiki/Cloud_storage. [5] Kent Beck with Cynthia Andres. Extreme Programming Explained. With a forew. by Erich Gamma. Addison-Wesley, Oct. 1999. 46 pp. isbn: 978-0321278654. url: http : / / ptgmedia . pearsoncmg . com / images / 9780321278654 / samplepages / 9780321278654.pdf. [6] eXtreme Programming. url: https://en.wikipedia.org/wiki/Extreme_programming. [7] Roy Thomas Fielding. “Architectural Styles and the Design of Network-based Soft- ware Architectures”. Information and Computer Science. University of California, Irvine, 2000. 180 pp. [8] Gherkin Wiki. url: https://github.com/cucumber/cucumber/wiki/Gherkin. [9] History of the Internet. url: https://en.wikipedia.org/wiki/History_of_the_Internet. [10] How to sell BDD to the business. url: https://skillsmatter.com/skillscasts/923-how- to-sell-bdd-to-the-business. [11] HTTP Verbs. url: https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html. [12] Internet Protocol. url: https://en.wikipedia.org/wiki/Internet_Protocol. [13] Internet protocol suite. url: https://en.wikipedia.org/wiki/Internet_protocol_suite. [14] Sunil Kamalakar. “Automatically Generating Tests from Natural Language De- scriptions of Software Behavior”. Information and Computer Science. Virginia Polytechnic Institute and State University, 2013. 72 pp. [15] List of HTTP status codes. url: https://www.w3.org/Protocols/rfc2616/rfc2616- sec10.html. [16] Natural language processing. url: https : / / en . wikipedia . org / wiki / Natural _ language_processing. [17] OpenAPI Specification. url: https://github.com/OAI/OpenAPI-Specification/blob/ master/versions/2.0.md. [18] RegExpWiki. url: https://en.wikipedia.org/wiki/Regular_expression. [19] Leonard Richardson and Mike Amundsen. RESTful Web APIs. With a forew. by Sam Ruby. 1st ed. O’Reilly Media, Sept. 2013. 404 pp. isbn: 978-1-449-35806-8. [20] Leonard Richardson and Sam Ruby. RESTful Web Services. 1st ed. O’Reilly Media, May 2007. 448 pp. isbn: 978-0-596-52926-0. [21] Michael Roth and Ewan Klein. “Parsing Software Requirements with an Ontology- based Semantic Role Labeler”. In: Proceedings of the IWCS Workshop: Language and Ontologies 2015. 2015. ΒΙΒΛΙΟΓΡΑΦΊΑ 190

[22] Michael Roth et al. “Software Requirements: A new Domain for Semantic Parsers”. In: (2014). [23] Michael Roth et al. “Software Requirements as an Application Domain for Natural Language Processing”. In: (). in preparation. [24] Mathias Soeken, Robert Wille1, and Rolf Drechsler. “Assisted Behavior Driven Development Using Natural Language Processing”. In: (). [25] Software Development Process. url: https : / / en . wikipedia . org / wiki / Software _ development_process. [26] Specification of Internet Transmission Control Program. url: https://tools.ietf.org/ html/rfc675. [27] Test Driven Development. url: https : / / en . wikipedia . org / wiki / Test - driven _ development. [28] The OpenAPI Specification. url: https://github.com/OAI/OpenAPI-Specification. [29] The Truth about BDD. url: https://sites.google.com/site/unclebobconsultingllc/the- truth-about-bdd. [30] Transmission Control Protocol. url: https://en.wikipedia.org/wiki/Transmission_ Control_Protocol. [31] Jim Webber, Savas Parastatidis, and Ian Robinson. REST in Practice. 1st ed. O’Reilly Media, Sept. 2010. 448 pp. isbn: 978-0-596-80582-1. [32] Matt Wynne and Aslak Hellesoy. The Cucumber Book. Ed. by Jacquelyn Carter. The Pragmatic Bookshelf, Jan. 2012. 328 pp. isbn: 978-1-934356-80-7.