API REST

Ιστορία

ΥΠΟΛΟΙΠΟ σημαίνει Re παρουσίασης S Tate Τ ΕΤΑΦΟΡΑ πρωτόκολλο. Ο Roy Fielding όρισε το REST στη διδακτορική του διατριβή το 2000.

Τι είναι το REST API;

Το REST αναπτύχθηκε για να παρέχει μια ομοιόμορφη διεπαφή για

  • Προσδιορισμός πόρων
  • Χειρισμός πόρων
  • Αυτο περιγραφικά μηνύματα
  • Χρησιμοποιώντας το Hypermedia ως Μηχανή Κατάστασης Εφαρμογών (HATEOS)

Βέλτιστες πρακτικές

Βασικά

Μέθοδος || //api.co/v2/cars || //api.co/v2/cars/1234

  • ΠΑΡΤΕ || Λίστα όλων των αυτοκινήτων || Ανακτήστε ένα μεμονωμένο αυτοκίνητο
  • ΑΝΑΚΟΙΝΩΣΗ || Δημιουργήστε ένα νέο αυτοκίνητο || Λάθος
  • ΒΑΘ || Αντικαταστήστε τις συλλογές αυτοκινήτων || Αντικαταστήστε το αυτοκίνητο με το αναγνωριστικό 1234

    με νέο

  • ΔΙΑΓΡΑΦΗ || Διαγραφή όλων των αυτοκινήτων || Διαγραφή αυτοκινήτου με αναγνωριστικό 1234

Σημειώστε ότι ενώ οι λειτουργίες PUT είτε ο πελάτης είτε ο διακομιστής μπορούν να δημιουργήσουν id

Τα ουσιαστικά είναι καλά Τα ρήματα είναι κακά

  • Χρησιμοποιήστε ουσιαστικά να αναφερθώ πόρους, όπως cars, fruitsκ.λπ.
  • Χρησιμοποιήστε ρήματα για δηλώσεις δράσης convertMilesToKms,getNutritionalValues

Μοναδικός ή πληθυντικός;

Χρησιμοποιήστε τη σωστή γραμματική για δήλωση

Αποφύγει/person/145

Προτιμήστε/people/154 να επιστρέψετε το 154ο άτομο από τη λίστα ατόμων

Χρησιμοποιήστε θήκες

Χρησιμοποιήστε οποιοδήποτε από τα παρακάτω μοτίβα και να είστε συνεπείς!

Στυλ θήκης //api.fintech.cp/DailyTransactions/TodayΠαράδειγμα ανώτερης κάμερας χαμηλότερηCamelCase //api.fintech.cp/dailyTransactions/todaysnake_case//api.fintech.cp/daily_transactions/today

Σχέσεις και πόροι

  • Πόροι μπορούν να έχουν one-to-many, many-to-many, many-to-oneσχέσεις κλπ Χαρτογράφηση τους σωστά είναι ζωτικής σημασίας.

Χαρτογράφηση One-to-Many

Για παράδειγμα, Tickets/145/messages/4προτείνει μια-προς-πολλές σχέση μεταξύ ticketsκαι messages. Δηλαδή το 1εισιτήριο έχει Nμηνύματα. Το μήνυμα δεν είναι αυτόνομος πόρος. Δεν μπορείς να έχεις /messages/4.

Χαρτογράφηση πολλών έως πολλών

Για παράδειγμα, /usergroups/345/users/56προτείνει επιλέξτε 345η ομάδα χρηστών και αποκτήστε χρήστη με αναγνωριστικό 56. Ωστόσο, ένας χρήστης μπορεί να είναι σε πολλαπλάσια, usergroupsδηλαδή /usergroups/209/users/56ισχύει επίσης. Σε τέτοια περίπτωση, για να διαχωρίσετε τον εξαρτώμενο πόρο usersσε ένα ξεχωριστό τελικό σημείο όπως /users/56και να παρέχετε πόρους που συνδέουν το/usergroups/209/users/56

Παράμετροι API

  • PATH : απαιτούνται για την πρόσβαση στον πόρο Π.χ./cars,/fruits
  • Παράμετροι ερωτήματος : προαιρετικό φιλτράρετε τη λίστα Π.χ./cars?type=SUV&year=2010
  • Κύριο μέρος : Ειδική λογική πόρων. Ερώτημα αναζήτησης εκ των προτέρων. Μερικές φορές μπορεί να έχει τόσο το ερώτημα όσο και το σώμα.
  • Κεφαλίδα : Πρέπει να περιέχει καθολικά ή πλατφόρμα δεδομένα. Π.χ. παράμετροι κλειδιού API, κρυπτογραφημένα κλειδιά για έλεγχο ταυτότητας, πληροφορίες τύπου συσκευής π.χ. κινητό ή επιτραπέζιο ή τελικό σημείο, τύπος δεδομένων συσκευής π.χ. xml ή json. Χρησιμοποιήστε την κεφαλίδα για να κοινοποιήσετε αυτές τις παραμέτρους

Κωδικοί κατάστασης HTTP

Χρησιμοποιήστε σωστούς κωδικούς κατάστασης

CodesMeaning1xxRequest ληφθεί και κατανοητό.2xxΗ ενέργεια που ζητήθηκε από τον πελάτη ελήφθη, κατανοήθηκε και ζητήθηκε. Οι περισσότεροι από αυτούς τους κωδικούς κατάστασης χρησιμοποιούνται στο URL Redirection.4xx Προορίζεται για καταστάσεις όπου φαίνεται ότι το σφάλμα προκλήθηκε από τον πελάτη.5xxΟ διακομιστής απέτυχε να εκπληρώσει ένα αίτημα.

Λίγο περισσότερο στο 2xx !

  • 201 Δημιουργήθηκε πόρος. Το POST/carsθα πρέπει να επιστρέψει το HTTP 201 που δημιουργήθηκε μεlocationκεφαλίδα δηλώνοντας πώς να αποκτήσετε πρόσβαση στον πόρο Π.χ .location:api.com/cars/124στην κεφαλίδα

202 - Αποδεκτό

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

204 - Χωρίς περιεχόμενο

Χρησιμοποιείται όταν διαγραφεί DELETE cars/124Επιστρέφει κανένα περιεχόμενο. Αλλά μπορεί επίσης να επιστρέψει 200 OKεάν το API σκοπεύει να στείλει τον διαγραμμένο πόρο για περαιτέρω επεξεργασία.

Οι επικίνδυνοι πόροι 5xx !

  • 500 εσωτερικό σφάλμα διακομιστή
  • 504 Χρονικό όριο Gateway. Ο διακομιστής δεν έλαβε έγκαιρη απάντηση

Το λιγότερο γνωστό 4xx υποδηλώνει ότι περνάτε λάθος παράμετρο. Μπορεί επίσης να διαβιβάσει πληροφορίες που είναι λανθασμένες. Π.χ

DELETE /cars/MH09234

επιστροφές 4xxή μήνυμαExpecting int car id /car/id got string car/MH09234