Διαδρομές & CRUD

Οι διαδρομές είναι τα σημεία εισόδου του API σας. Είναι ομαδοποιημένες ανά πόρο, και μπορείτε να τις γράψετε με το χέρι ή να τις παράξετε από ένα μοντέλο.

Ορισμός μιας διαδρομής

Μια διαδρομή φέρει μια μέθοδο, μια διαδρομή, παραμέτρους και αποκρίσεις. Η διαδρομή χρησιμοποιεί τη σύνταξη {{param}} του Restorm: μόλις πληκτρολογήσετε {{id}} στη διαδρομή, εμφανίζεται η αντίστοιχη παράμετρος· η αφαίρεσή της τη διαγράφει.

Οι παράμετροι

Η καρτέλα Ορισμός μιας διαδρομής απαριθμεί τις παραμέτρους της — τις παραμέτρους διαδρομής (που δημιουργούνται από τους δείκτες θέσης {{param}}) και τις παραμέτρους ερωτήματος / κεφαλίδας που προσθέτετε με το Προσθήκη παραμέτρου. Καθεμία φέρει ένα όνομα, μια θέση (σε), τον απαιτούμενο χαρακτήρα της, μια περιγραφή και, προαιρετικά, ένα παράδειγμα.

Το κελί Τύπος είναι ένα σύνθετο πλαίσιο: επιλέξτε ένα πρωτόγονο (string, integer, number, boolean) ή ένα από τα ονομασμένα enums του σχεδίου με ένα μόνο κλικ. Για τις πιο σύνθετες περιπτώσεις, επιλέξτε Advanced… για να ανοίξετε ένα μικρό παράθυρο διαλόγου όπου μπορείτε:

• να κάνετε την παράμετρο έναν πίνακα και να επιλέξετε τον τύπο στοιχείου της (array<string>, …) — μια παράμετρος ερωτήματος πολλαπλών τιμών·
• να της δώσετε inline τιμές enum (το επιτρεπόμενο σύνολο, σε μορφή chips) όταν δεν τυποποιείται από ένα ονομασμένο enum·
• Εξαγωγή σε ονομασμένο enum — να προάγετε αυτές τις inline τιμές σε ένα κοινόχρηστο enum (δείτε Μοντέλα & enums).

Μια παράμετρος μπορεί επίσης να είναι συνδεδεμένη με μια ιδιότητα μοντέλου (η στήλη Σύνδεσμος μοντέλου), κληρονομώντας τον τύπο της, ή να επισημανθεί ως καταργημένη. Κάθε παράμετρος — ο τύπος της, το enum της, η κατάργησή της — μεταφέρεται στην παραγόμενη τεκμηρίωση και σε κάθε προβολή πρωτοκόλλου.

Παραγωγή CRUD

Από τις ρυθμίσεις ενός μοντέλου, το Παραγωγή CRUD δημιουργεί με ένα κλικ μια ομάδα διαδρομών ονομασμένη σύμφωνα με τον πληθυντικό του μοντέλου, με έξι διαδρομές:

Διαδρομή	Μέθοδος & διαδρομή	Αποκρίσεις
Λίστα	GET / (σελιδοποιημένο)	200
Ανάκτηση	GET /{{id}}	200 · 404
Δημιουργία	POST /	201
Αντικατάσταση	PUT /{{id}}	200 · 404
Ενημέρωση	PATCH /{{id}}	200 · 404
Διαγραφή	DELETE /{{id}}	204 · 404

Η λίστα είναι σελιδοποιημένη (offset, 20 στοιχεία προεπιλεγμένα, 100 το μέγιστο). Κάθε {{id}} είναι αυτόματα συνδεδεμένο με το αναγνωριστικό του μοντέλου.

Το παράθυρο διαλόγου Παραγωγή CRUD προσφέρει δύο επιλογές:

• Αντικατάσταση των υπαρχουσών διαδρομών — για την αποφυγή διπλότυπων αν αναπαράξετε.
• Προστασία των διαδρομών εγγραφής με έλεγχο ταυτότητας — η δημιουργία, η αντικατάσταση, η ενημέρωση και η διαγραφή απαιτούν τότε ένα διακριτικό (bearer), ενώ οι αναγνώσεις παραμένουν δημόσιες.

Υπενθυμίζει επίσης ότι το CRUD σερβίρεται σε κάθε πρωτόκολλο: διαδρομές REST, ερωτήματα και μεταλλάξεις GraphQL, μέθοδοι gRPC, σύνολο οντοτήτων OData και λειτουργίες SOAP (δείτε Σερβίρισμα του σχεδίου ως mock).

Παραγωγή διαδρομών αναζήτησης

Για κάθε ιδιότητα σημειωμένη ως searchable, το Παραγωγή διαδρομών αναζήτησης προσθέτει μια παράμετρο ερωτήματος συνδεδεμένη με τη διαδρομή λίστας του μοντέλου (και δημιουργεί αυτή τη διαδρομή αν δεν υπάρχει ακόμη).

Έλεγχος ταυτότητας

Ο έλεγχος ταυτότητας ρυθμίζεται σε τρία επίπεδα: μια προεπιλεγμένη τιμή του σχεδίου, ένας απαιτούμενος έλεγχος ταυτότητας ανά ομάδα, και μια αντικατάσταση ανά διαδρομή (που κληρονομεί την προεπιλογή της ομάδας). Οι διαθέσιμες λειτουργίες είναι Καμία, Bearer (JWT), Κλειδί API (κεφαλίδα) και Basic.

Οι ετικέτες

Οι ετικέτες (tags) ομαδοποιούν τις διαδρομές για την τεκμηρίωση και την εξαγωγή OpenAPI. Υπάρχουν σε δύο επίπεδα: μια διαδρομή φέρει τις δικές της ετικέτες (η καρτέλα της Ορισμός), και μια ομάδα φέρει κοινές ετικέτες (οι ρυθμίσεις της) που εφαρμόζονται σε κάθε διαδρομή που περιέχει. Οι πραγματικές ετικέτες μιας διαδρομής είναι η ένωση των δύο — έτσι μια ετικέτα κοινή σε μια ολόκληρη ομάδα ορίζεται κατά προτίμηση μία μόνο φορά στην ομάδα. Όταν μετατρέπετε ένα εισαγόμενο API σε σχέδιο, μια ετικέτα κοινή σε όλες τις διαδρομές μιας ομάδας ανεβαίνει αυτόματα στην ομάδα.

Η κατάργηση

Μια διαδρομή (όπως μια ιδιότητα ή μια παράμετρος) μπορεί να επισημανθεί ως καταργημένη από τις Ρυθμίσεις της. Μια καταργημένη διαδρομή εμφανίζεται αχνή στη λίστα των Διαδρομών και στους παραγόμενους πελάτες, και φέρει μια ειδοποίηση κατάργησης στην καρτέλα της. Η σημαία μεταφέρεται σε κάθε προβολή πρωτοκόλλου — το deprecated του OpenAPI, η οδηγία @deprecated του GraphQL, οι περιγραφείς SOAP και gRPC, και τα μεταδεδομένα OData — ώστε να τη βλέπουν οι καταναλωτές οποιουδήποτε σερβιριζόμενου πρωτοκόλλου.