REST API: τι είναι, μέθοδοι HTTP και αρχή λειτουργίας σε κινητές εφαρμογές

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

REST API (Representational State Transfer API) είναι ένα αρχιτεκτονικό στυλ που προτάθηκε από τον Roy Fielding στη διδακτορική του διατριβή το 2000. Ορίζει ένα σύνολο περιορισμών και αρχών για τον σχεδιασμό πρωτοκόλλων δικτύου. Ένα API που συμμορφώνεται με αυτούς τους περιορισμούς ονομάζεται RESTful. Το REST δεν είναι πρωτόκολλο ή πρότυπο είναι μια αρχιτεκτονική προσέγγιση που χρησιμοποιεί υπάρχοντα πρωτόκολλα (κυρίως HTTP) για ανταλλαγή δεδομένων μεταξύ πελάτη και διακομιστή.

Η βασική ιδέα του REST είναι αρχιτεκτονική βασισμένη σε πόρους. Αντί να καλεί μεθόδους στον διακομιστή (όπως στο SOAP ή RPC), ο πελάτης λειτουργεί σε πόρους: λαμβάνει τη λίστα τους, δημιουργεί νέους, ενημερώνει ή διαγράφει. Κάθε πόρος είναι μια οντότητα τομέα: χρήστης, παραγγελία, προϊόν, άρθρο. Ο πόρος έχει μια κατάσταση που μεταβιβάζεται στον πελάτη σε τυποποιημένη μορφή, συνήθως JSON. Ο διακομιστής δεν αποθηκεύει την κατάσταση του πελάτη μεταξύ αιτημάτων αυτή είναι η αρχή stateless, βασική απαίτηση του REST.

Βασικά χαρακτηριστικά REST API:

• Stateless κάθε αίτημα από τον πελάτη περιέχει όλες τις πληροφορίες που απαιτούνται για την επεξεργασία του
• Cacheable οι απαντήσεις του διακομιστή πρέπει να επισημαίνονται ρητά ως αποθηκεύσιμες ή μη στην κρυφή μνήμη
• Layered system η αρχιτεκτονική μπορεί να περιλαμβάνει ενδιάμεσους διακομιστές, εξισορροπητές φορτίου, proxy
• Uniform interface ομοιόμορφη διεπαφή αλληλεπίδρασης μέσω HTTP μεθόδων, URL και κωδικών κατάστασης

Αρχές της REST αρχιτεκτονικής

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

Η αρχή Uniform Interface επιπλέον περιλαμβάνει τέσσερις υπο-περιορισμούς: αναγνώριση πόρων μέσω URI, χειρισμό πόρων μέσω αναπαραστάσεων, αυτοπεριγραφικά μηνύματα και HATEOAS (υπερμέσα ως μηχανή κατάστασης εφαρμογής). Ο τελευταίος υπο-περιορισμός συχνά αγνοείται στην πράξη τα περισσότερα σύγχρονα REST API δεν εφαρμόζουν πλήρως το HATEOAS, που οδηγεί σε συζητήσεις για το αν ένα τέτοιο API είναι "πραγματικά" RESTful.

Η αρχή Stateless μία από τις πιο σημαντικές για την κλιμάκωση. Η απουσία συνεδριών στον διακομιστή σημαίνει ότι οποιαδήποτε περίπτωση του διακομιστή μπορεί να επεξεργαστεί οποιοδήποτε αίτημα. Αυτό απλοποιεί την οριζόντια επέκταση: αρκεί να προσθέσετε νέους διακομιστές πίσω από τον εξισορροπητή φορτίου. Για εφαρμογές κινητών, το stateless σημαίνει επίσης ότι το αίτημα μπορεί να σταλεί σε οποιονδήποτε διακομιστή CDN, που είναι κρίσιμο για την παγκόσμια προσβασιμότητα.

HTTP μέθοδοι στο REST

Κάθε HTTP μέθοδος στο REST API αντιστοιχεί σε μια συγκεκριμένη λειτουργία σε έναν πόρο: GET για ανάγνωση, POST για δημιουργία, PUT για πλήρη ενημέρωση, PATCH για μερική ενημέρωση, DELETE για διαγραφή. Η αδεμποτεντότητα των μεθόδων είναι βασικό χαρακτηριστικό: GET, PUT, DELETE είναι αδεμποτεντές (η επαναλαμβανόμενη εκτέλεση δίνει το ίδιο αποτέλεσμα), το POST και PATCH δεν είναι. Αυτό είναι σημαντικό για τον χειρισμό σφαλμάτων δικτύου όταν ο πελάτης δεν γνωρίζει αν το αίτημα έφτασε στον διακομιστή.

• GET λήψη ενός πόρου ή λίστας πόρων. Αδεμποτεντές, δεν αλλάζει την κατάσταση του διακομιστή
• POST δημιουργία νέου πόρου. Δεν είναι αδεμποτεντές, κάθε κλήση δημιουργεί νέο πόρο
• PUT πλήρης αντικατάσταση πόρου. Αδεμποτεντές, η επαναλαμβανόμενη κλήση δεν αλλάζει κατάσταση μετά την πρώτη
• PATCH μερική ενημέρωση πόρου. Μερικώς αδεμποτεντές (εξαρτάται από την υλοποίηση)
• DELETE διαγραφή πόρου. Αδεμποτεντές, η επαναλαμβανόμενη διαγραφή επιστρέφει 404, όχι σφάλμα

Οι κωδικοί κατάστασης HTTP είναι αναπόσπαστο μέρος του REST API. Κάθε κωδικός έχει συγκεκριμένη σημασία: 200 OK για επιτυχημένο GET, 201 Created για POST, 204 No Content για DELETE χωρίς σώμα απάντησης, 400 Bad Request για μη έγκυρα δεδομένα, 401 Unauthorized για έλλειψη πιστοποίησης, 404 Not Found για απουσία πόρου. Η σωστή χρήση κωδικών κατάστασης κάνει το API αυτο-τεκμηριώσιμο και απλοποιεί τον εντοπισμό σφαλμάτων.

Μορφές δεδομένων: JSON και άλλες

JSON (JavaScript Object Notation) η κύρια μορφή μεταφοράς δεδομένων στο REST API. Η δημοφιλία του εξηγείται από την απλότητα, την αναγνωσιμότητα από τον άνθρωπο και την εγγενή υποστήριξη στο JavaScript. Το JSON μεταφέρεται με την κεφαλίδα Content-Type: application/json. Οι εναλλακτικές περιλαμβάνουν XML (ογκώδης, παρωχημένο), YAML (βολικό για διαμόρφωση, σπάνιο για API) και Protocol Buffers (δυαδικό, αποτελεσματικό για συστήματα υψηλής φόρτωσης).

Η δομή ενός αντικειμένου JSON στο REST API συνήθως περιλαμβάνει τα πεδία id, type και τα χαρακτηριστικά του πόρου. Για συλλογές χρησιμοποιείται ένας πίνακας JSON με μεταδεδομένα σελιδοποίησης. Τα σύγχρονα REST API ακολουθούν την προδιαγραφή JSON:API (jsonapi.org) ή JSON Schema για επικύρωση απαντήσεων. Η χρήση ενιαίας μορφής δεδομένων απλοποιεί την ανάπτυξη βιβλιοθηκών πελάτη και τη δημιουργία τεκμηρίωσης.

Παράδειγμα απάντησης JSON για λίστα χρηστών:

{
    "data": [
        {
            "id": 1,
            "name": "Άννα Πετρόβα",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Η επιλογή της μορφής μεταφοράς δεδομένων επηρεάζει την απόδοση της εφαρμογής κινητού. Το JSON συμπιέζεται μέσω GZIP κατά 70-80%, καθιστώντας το αποδεκτό για τα περισσότερα σενάρια. Για εφαρμογές σε πραγματικό χρόνο με μεγάλο όγκο δεδομένων (streaming, παιχνίδια) συνιστάται η μετάβαση σε δυαδικά πρωτόκολλα ή η χρήση WebSocket σε συνδυασμό με Protocol Buffers.

Παραδείγματα REST API αιτημάτων

Ας δούμε πρακτικά παραδείγματα εργασίας με REST API από την πλευρά της εφαρμογής κινητού. Ως παράδειγμα, ας πάρουμε ένα API για διαχείριση παραγγελιών σε ένα ηλεκτρονικό κατάστημα. Για κάθε HTTP μέθοδο παρουσιάζεται το αίτημα και η αναμενόμενη απάντηση του διακομιστή. Τα παραδείγματα δείχνουν την τυπική δομή RESTful API που χρησιμοποιείται στην ανάπτυξη κινητών.

GET λήψη λίστας παραγγελιών

Αίτημα για λήψη όλων των παραγγελιών του χρήστη με σελιδοποίηση. Η απάντηση περιέχει έναν πίνακα αντικειμένων παραγγελίας και μεταπληροφορίες για πλοήγηση σελίδων. Οι παράμετροι page και per_page μεταβιβάζονται μέσω query string.

// Διεπαφή Retrofit για REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST δημιουργία νέας παραγγελίας

Δημιουργία νέας παραγγελίας μέσω ενός POST αιτήματος. Ο διακομιστής επιστρέφει κατάσταση 201 Created και το δημιουργημένο αντικείμενο στο σώμα της απάντησης. Σημαντικό: η δημιουργία γίνεται στη συλλογή /api/v1/orders, όχι σε έναν συγκεκριμένο πόρο αυτό είναι ένα τυπικό RESTful μοτίβο.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Παράδειγμα σώματος αιτήματος
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE διαγραφή παραγγελίας

Η διαγραφή ενός πόρου γίνεται με τη μέθοδο DELETE στο συγκεκριμένο URL της παραγγελίας. Η επιτυχημένη διαγραφή επιστρέφει 204 No Content. Η αδεμποτεντότητα του DELETE σημαίνει ότι ένα επαναλαμβανόμενο αίτημα στο ίδιο URL θα επιστρέψει 404 Not Found, το οποίο χειρίζεται σωστά από τον πελάτη.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Χρήση σε ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Αυτά τα παραδείγματα δείχνουν την τυπική υλοποίηση REST API στην πλευρά Android χρησιμοποιώντας Retrofit και Kotlin Coroutines. Για εφαρμογές iOS, παρόμοιο ρόλο παίζουν το URLSession ή η βιβλιοθήκη Alamofire σε συνδυασμό με τα πρωτόκολλα Codable. Η δομή του REST API παραμένει η ίδια ανεξάρτητα από πλατφόρμα αλλάζει μόνο ο τρόπος εκτέλεσης των αιτημάτων.

Σχεδίαση RESTful API: πρακτικές συστάσεις

Η σχεδίαση ενός ποιοτικού RESTful API απαιτεί τήρηση συμβάσεων που κάνουν το API διαισθητικό για προγραμματιστές. Οι πόροι πρέπει να ονομάζονται με ουσιαστικά στον πληθυντικό αριθμό (/users, /orders, /products), οι HTTP μέθοδοι πρέπει να αντικατοπτρίζουν τις λειτουργίες και τα URL την ιεραρχική δομή. Τα σφάλματα πρέπει να επιστρέφουν ένα τυποποιημένο JSON με κωδικό και μήνυμα, όχι απλώς HTTP κατάσταση. Η τήρηση αυτών των συμβάσεων μειώνει το εμπόδιο εισόδου για νέους προγραμματιστές και απλοποιεί την ενοποίηση.

• Ονομασία πόρων πληθυντικός, kebab-case: /api/v1/user-orders, όχι /api/v1/getUserOrders
• Φιλτράρισμα και ταξινόμηση μέσω query παραμέτρων: ?status=active&sort=created_at:desc
• Σελιδοποίηση cursor-based για μεγάλα σύνολα, page-based για μικρά
• Έκδοση μέσω URL (/api/v2/) ή κεφαλίδας Accept-Version
• Σφάλματα ενιαία μορφή: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting κεφαλίδες X-RateLimit-Remaining και Retry-After

Ένα από τα συχνά λάθη στη σχεδίαση REST API είναι η υπερβολική ένθεση πόρων. Αντί για /users/1/orders/5/items/3, είναι καλύτερο να χρησιμοποιείτε επίπεδη δομή με query παραμέτρους: /items?order_id=5&user_id=1. Αυτό απλοποιεί την προσωρινή αποθήκευση, δεν απαιτεί υποστήριξη μεγάλων διαδρομών στον διακομιστή και είναι ευκολότερο να τεκμηριωθεί. Η επίπεδη αρχιτεκτονική είναι επίσης πιο συμβατή με graph-based ερωτήματα κατά τη μετάβαση σε GraphQL στο μέλλον.

Η ασφάλεια REST API πραγματοποιείται μέσω πιστοποίησης (JWT, OAuth 2.0) και εξουσιοδότησης σε επίπεδο πόρου. Κάθε αίτημα πρέπει να ελέγχει αν ο χρήστης έχει πρόσβαση στον ζητούμενο πόρο. Το HTTPS είναι υποχρεωτικό χωρίς κρυπτογράφηση, τα διακριτικά και τα δεδομένα μεταφέρονται σε απλό κείμενο. Για εφαρμογές κινητών, συνιστάται η χρήση OAuth 2.0 με PKCE (Proof Key for Code Exchange) για ασφαλή λήψη διακριτικών.

Έκδοση και προσωρινή αποθήκευση

Η έκδοση REST API είναι απαραίτητη για συμβατότητα προς τα πίσω κατά τις αλλαγές. Οι πιο συνηθισμένες προσεγγίσεις: έκδοση στο URL (/api/v1/orders), έκδοση στην κεφαλίδα (Accept: application/vnd.myapi.v1+json) και έκδοση στην παράμετρο query (?api_version=1). Η έκδοση URL είναι η πιο δημοφιλής μέθοδος επειδή είναι σαφώς ορατή σε αρχεία καταγραφής και τεκμηρίωση. Ωστόσο, παραβιάζει την αρχή REST για μοναδικό URL πόρου.

Η προσωρινή αποθήκευση στο REST API πραγματοποιείται μέσω HTTP κεφαλίδων Cache-Control, ETag και Last-Modified. Τα GET αιτήματα που επισημαίνονται ως αποθηκεύσιμα μπορούν να εξυπηρετούνται από την κρυφή μνήμη του προγράμματος περιήγησης ή του proxy χωρίς να καλούν τον διακομιστή. Για εφαρμογές κινητών, η προσωρινή αποθήκευση είναι ιδιαίτερα σημαντική μειώνει την κατανάλωση δεδομένων και επιταχύνει την εμφάνιση προηγουμένως φορτωμένων δεδομένων σε κακή σύνδεση. Το ETag είναι ένα κατακερματισμός του περιεχομένου της απάντησης: ο πελάτης το στέλνει στο If-None-Match και ο διακομιστής επιστρέφει 304 Not Modified αν τα δεδομένα δεν έχουν αλλάξει.

Οι σύγχρονες εναλλακτικές REST API περιλαμβάνουν GraphQL (ευέλικτη επιλογή δεδομένων από τον πελάτη) και gRPC (δυαδικό πρωτόκολλο σε HTTP/2 για μικρουπηρεσίες). Το REST παραμένει ωστόσο το κύριο πρότυπο για δημόσια API χάρη στην απλότητα, την καθολικότητα και την ευρεία υποστήριξη εργαλείων. Η επιλογή μεταξύ REST και εναλλακτικών εξαρτάται από τις συγκεκριμένες απαιτήσεις του έργου: πολυπλοκότητα αιτημάτων, όγκος δεδομένων, απαιτήσεις για ενημερώσεις σε πραγματικό χρόνο.