Πώς να φτιάξετε ένα REST API: σχεδιασμός, ασφάλεια και δημοσίευση

Για να φτιάξετε ένα REST API, καταγράψτε τους πόρους που διαχειρίζεται η εφαρμογή σας (χρήστες, παραγγελίες, κρατήσεις), δώστε σε καθέναν ένα URL όπως /orders και /orders/{id}, και χρησιμοποιήστε μεθόδους HTTP για τις ενέργειες: GET για ανάγνωση, POST για δημιουργία, PATCH για ενημέρωση, DELETE για διαγραφή. Επιστρέψτε JSON με σωστούς κωδικούς κατάστασης, επικυρώστε κάθε είσοδο, απαιτήστε έλεγχο ταυτότητας και ελέγχους δικαιωμάτων ανά εγγραφή στον διακομιστή, και σελιδοποιήστε τις λίστες. Έπειτα τεκμηριώστε τα endpoints και δημοσιεύστε το API πίσω από HTTPS.

Αυτός ο οδηγός καλύπτει τις αποφάσεις σχεδίασης, ένα παράδειγμα συνόλου διαδρομών, prompts για έναν AI app builder και τα λάθη που δημιουργούν κενά ασφαλείας. Αν τα API είναι καινούργια για εσάς, ξεκινήστε με το τι είναι ένα API.

Πότε χρειάζεστε ένα REST API

• Το web frontend σας πρέπει να αποθηκεύει και να φορτώνει δεδομένα από διακομιστή
• Μια εφαρμογή για κινητά, ένας συνεργάτης ή ένα εργαλείο αυτοματισμού χρειάζεται πρόσβαση στα δεδομένα σας
• Άλλες υπηρεσίες σας στέλνουν γεγονότα (webhooks)
• Μοιράζετε τη δουλειά ανάμεσα σε μια ομάδα frontend και μια ομάδα backend

Το REST είναι το πιο συνηθισμένο στυλ, αλλά όχι το μόνο. Το REST vs GraphQL εξηγεί πότε ένα ενιαίο, ευέλικτο endpoint ερωτημάτων ταιριάζει καλύτερα.

Σχεδιάστε πρώτα: πόροι και διαδρομές

Γράψτε τα ουσιαστικά της εφαρμογής σας και τι κάνουν οι χρήστες με αυτά. Για μια απλή εφαρμογή κρατήσεων:

Αυτές αντιστοιχούν σε δημιουργία, ανάγνωση, ενημέρωση και διαγραφή· δείτε το τι είναι το CRUD. Συμβάσεις που αξίζει να ακολουθήσετε:

• Ουσιαστικά στον πληθυντικό, χωρίς ρήματα στα URL: /bookings, όχι /getBookings.
• Φωλιάστε μόνο ένα επίπεδο όταν διευκρινίζει την ιδιοκτησία: /bookings/{id}/notes.
• Ενέργειες που δεν είναι CRUD μπορούν να είναι υπο-πόροι: το POST /bookings/{id}/cancel είναι πιο σαφές από ένα «μαγικό» PATCH.
• Συνεπής ονοματολογία για τα πεδία, όπως created_at παντού.

Κωδικοί κατάστασης και σφάλματα

Χρησιμοποιήστε τυπικούς κωδικούς HTTP, ώστε οι πελάτες να ξέρουν τι συνέβη χωρίς να αναλύουν κείμενο:

Επιστρέφετε τα σφάλματα σε ένα συνεπές σχήμα JSON, για παράδειγμα {"error": {"code": "slot_taken", "message": "Αυτή η ώρα δεν είναι πλέον διαθέσιμη."}}, και ποτέ μην περιλαμβάνετε stack traces ή σφάλματα βάσης δεδομένων στις απαντήσεις.

Επιλογές και συμβιβασμοί

Βήμα προς βήμα

1. Καταγράψτε τους πόρους και τις διαδρομές όπως παραπάνω, μαζί με το ποιος μπορεί να καλεί καθεμία.
2. Μοντελοποιήστε τα δεδομένα στη βάση σας, με τα πεδία και τις σχέσεις που χρειάζεστε.
3. Φτιάξτε πρώτα τις διαδρομές ανάγνωσης, και μετά δημιουργία, ενημέρωση και διαγραφή.
4. Επικυρώστε την είσοδο σε κάθε εγγραφή με μια βιβλιοθήκη σχήματος: υποχρεωτικά πεδία, τύποι, μήκη, επιτρεπτές τιμές. Απορρίψτε τα άγνωστα πεδία.
5. Προσθέστε έλεγχο ταυτότητας, και έπειτα εξουσιοδότηση ανά εγγραφή: η φόρτωση του /bookings/42 πρέπει να ελέγχει ότι η κράτηση 42 ανήκει στον καλούντα, και όχι μόνο ότι κάποιος έχει συνδεθεί.
6. Σελιδοποιήστε κάθε λίστα και ορίστε ανώτατο μέγεθος σελίδας.
7. Περιορίστε τον ρυθμό στη σύνδεση και στις ακριβές διαδρομές. Δείτε το όριο ρυθμού αιτημάτων.
8. Ρυθμίστε το CORS μόνο αν προγράμματα περιήγησης σε άλλους τομείς πρέπει να καλούν το API, και καταγράψτε ρητά αυτές τις προελεύσεις. Το πώς να διορθώσετε σφάλματα CORS εξηγεί τα σφάλματα που θα δείτε.
9. Γράψτε τεκμηρίωση και δοκιμές για κάθε διαδρομή, συμπεριλαμβανομένων των περιπτώσεων αποτυχίας.
10. Δημοσιεύστε με τα μυστικά σε μεταβλητές περιβάλλοντος, HTTPS, καταγραφές και έλεγχο υγείας.

Prompts για τον AI builder σας

Σκελετός:

Φτιάξε ένα REST API για κρατήσεις με αυτές τις διαδρομές: GET /api/health, GET /api/bookings (σελιδοποιημένο, έως 50 ανά σελίδα), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Αποθήκευσε τα δεδομένα στη βάση μας. Επικύρωσε τα σώματα των αιτημάτων με μια βιβλιοθήκη σχήματος και απέρριψε άγνωστα πεδία. Επίστρεψε σφάλματα JSON της μορφής {"error": {"code", "message"}} με σωστούς κωδικούς κατάστασης (400, 401, 403, 404, 409). Κράτα τα μυστικά σε μεταβλητές περιβάλλοντος.

Ασφάλεια:

Απαίτησε σύνδεση σε κάθε διαδρομή bookings. Σε κάθε ανάγνωση, ενημέρωση και διαγραφή, έλεγξε στον διακομιστή ότι η κράτηση ανήκει στον τρέχοντα χρήστη· επίστρεψε 404 αν δεν ανήκει. Μην δέχεσαι ποτέ IDs χρηστών ή ρόλους από το σώμα του αιτήματος. Περιόρισε το POST /api/bookings σε 20 ανά λεπτό ανά χρήστη. Κατέγραφε τα σφάλματα στον διακομιστή χωρίς να επιστρέφεις stack traces.

Τεκμηρίωση:

Γράψε μια περιγραφή OpenAPI για αυτές τις διαδρομές, και ένα σύντομο README με παραδείγματα αιτημάτων και απαντήσεων για κάθε μία.

Δοκιμή του API σας

Δοκιμάστε το από έξω από το frontend, γιατί το ίδιο θα κάνουν και οι επιτιθέμενοι:

• Κάθε διαδρομή λειτουργεί με έγκυρη είσοδο και επιστρέφει την τεκμηριωμένη δομή και κωδικό
• Τα λείποντα ή άκυρα πεδία επιστρέφουν 400 με ένα σαφές μήνυμα
• Χωρίς token, κάθε προστατευμένη διαδρομή επιστρέφει 401
• Ο χρήστης Α που ζητά την εγγραφή του χρήστη Β με ID παίρνει 404 ή 403
• Οι λίστες είναι σελιδοποιημένες, και ένα τεράστιο limit περιορίζεται
• Οι διπλές ή συγκρουόμενες δημιουργίες επιστρέφουν 409, όχι 500
• Τα όρια ρυθμού επιστρέφουν 429
• Οι απαντήσεις σφάλματος δεν περιέχουν stack traces, SQL ή μυστικά
• Το CORS επιτρέπει μόνο τις προελεύσεις που θέλετε

Συχνά λάθη

• Έλεγχος σύνδεσης χωρίς έλεγχο ιδιοκτησίας. Η πιο συνηθισμένη τρύπα σε API: οποιοσδήποτε συνδεδεμένος χρήστης μπορεί να διαβάσει οποιαδήποτε εγγραφή αλλάζοντας το ID.
• Εμπιστοσύνη στον πελάτη. Τιμές, ρόλοι και IDs χρηστών από το σώμα του αιτήματος μπορούν να αλλάξουν.
• Επιστροφή ολόκληρων γραμμών βάσης. Τα hash κωδικών και τα εσωτερικά πεδία διαρρέουν. Επιλέξτε τι περιλαμβάνει κάθε απάντηση.
• Λίστες χωρίς όριο. Ένα αίτημα για κάθε εγγραφή μπορεί να επιβραδύνει ολόκληρη την εφαρμογή.
• 200 OK με μήνυμα σφάλματος μέσα. Οι πελάτες και η παρακολούθηση δεν μπορούν να καταλάβουν ότι απέτυχε.
• CORS ρυθμισμένο να επιτρέπει τα πάντα σε API που χρησιμοποιεί cookies.
• Χωρίς έλεγχο υγείας ή καταγραφές, οπότε μαθαίνετε για διακοπές από τους χρήστες.

Για έναν ευρύτερο έλεγχο πριν από την κυκλοφορία, δείτε τη λίστα ελέγχου ασφαλείας για εφαρμογές που φτιάχνονται με AI.

Χτίζοντας ένα REST API στο Mythex

Μπορείτε να ζητήσετε από το Mythex ένα API ως μέρος της εφαρμογής σας ή ως δική του υπηρεσία. Ο οδηγός REST API backend της τεκμηρίωσης έχει ένα αρχικό prompt: ονομάστε το framework και τις διαδρομές σας, ζητήστε σαφή σφάλματα JSON, κρατήστε τα μυστικά σε μεταβλητές περιβάλλοντος και συμπεριλάβετε ένα Dockerfile. Τα container backends σε Node, Python, C#, Java και άλλες γλώσσες δημοσιεύονται μέσω Dockerfile, και το Mythex αναλαμβάνει το deploy από το Publish (API backends). Ένα έργο μπορεί να τρέχει έναν ιστότοπο και έναν διακομιστή API μαζί, και μπορείτε να μεταβαίνετε ανάμεσά τους στην προεπισκόπηση. Αποθηκεύστε τα κλειδιά ως μυστικά του έργου, και αν το API χρειάζεται βάση δεδομένων, ζητήστε την στο chat. Για προγραμματισμένες εργασίες γύρω από το API σας, δείτε πώς να τρέχετε εργασίες παρασκηνίου.

Ερωτήσεις