REST API: What It Is, HTTP Methods, and How It Works in Mobile Apps

What is REST API?

REST API (Representational State Transfer API) is an architectural style proposed by Roy Fielding in his doctoral dissertation in 2000. It defines a set of constraints and principles for designing network protocols. An API that complies with these constraints is called RESTful. REST is not a protocol or standard — it is an architectural approach that uses existing protocols (primarily HTTP) for data exchange between client and server.

The key idea of REST is resource-oriented architecture. Instead of calling methods on the server (as in SOAP or RPC), the client operates on resources: retrieves lists, creates new ones, updates, or deletes them. Each resource is a domain entity: user, order, product, article. A resource has a state that is transmitted to the client in a standardized format, usually JSON. The server does not store the client state between requests — this is the stateless principle, a key requirement of REST.

Key characteristics of REST API:

• Stateless — each request from the client contains all the information needed for processing
• Cacheable — server responses must be explicitly marked as cacheable or non-cacheable
• Layered system — the architecture may include intermediate servers, load balancers, proxies
• Uniform interface — a single interaction interface via HTTP methods, URLs, and status codes

Principles of REST Architecture

REST is based on six architectural constraints formulated by Fielding. Compliance with these constraints ensures scalability, performance, and ease of integration. Each principle addresses a specific problem of distributed systems — from caching requirements to security demands. Let us examine each principle in detail.

The Uniform Interface principle additionally includes four sub-constraints: resource identification via URI, resource manipulation through representations, self-descriptive messages, and HATEOAS (Hypermedia as the Engine of Application State). The last sub-constraint is often ignored in practice — most modern REST APIs do not fully implement HATEOAS, which leads to discussions about whether such an API is “really” RESTful.

The Stateless principle is one of the most important for scaling. The absence of server-side sessions means that any server instance can handle any request. This simplifies horizontal scaling: simply add new servers behind a load balancer. For mobile applications, stateless also means that a request can be sent to any CDN server, which is critical for global availability.

HTTP Methods in REST

Each HTTP method in REST API corresponds to a specific operation on a resource: GET for reading, POST for creating, PUT for full update, PATCH for partial update, DELETE for deletion. Idempotence of methods is a key characteristic: GET, PUT, DELETE are idempotent (repeated execution yields the same result), POST and PATCH are not. This is important for handling network errors when the client does not know whether the request reached the server.

• GET — retrieving a resource or list of resources. Idempotent, does not change server state
• POST — creating a new resource. Not idempotent, each call creates a new resource
• PUT — full resource replacement. Idempotent, repeated calls do not change state after the first
• PATCH — partial resource update. Partially idempotent (depends on implementation)
• DELETE — resource deletion. Idempotent, repeated deletion returns 404, not an error

HTTP status codes are an integral part of REST API. Each code carries a specific meaning: 200 OK for successful GET, 201 Created for POST, 204 No Content for DELETE without a response body, 400 Bad Request for invalid data, 401 Unauthorized for missing authentication, 404 Not Found for missing resource. Proper use of status codes makes the API self-documenting and simplifies debugging.

Data Formats: JSON and Others

JSON (JavaScript Object Notation) is the primary data format for data transfer in REST API. Its popularity is due to simplicity, human readability, and native support in JavaScript. JSON is transmitted with the Content-Type: application/json header. Alternatives include XML (verbose, aging), YAML (convenient for configuration, less common for APIs), and Protocol Buffers (binary, efficient for high-load systems).

The structure of a JSON object in REST API typically includes id, type fields and resource attributes. For collections, a JSON array with pagination metadata is used. Modern REST APIs follow the JSON:API specification (jsonapi.org) or JSON Schema for response validation. Using a unified data format simplifies client library development and documentation generation.

Example JSON response for a list of users:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

The choice of data transfer format affects mobile application performance. JSON compresses via GZIP by 70-80%, making it acceptable for most scenarios. For real-time applications with large data volumes (streaming, gaming), it is recommended to switch to binary protocols or use WebSocket in combination with Protocol Buffers.

REST API Request Examples

Let us look at practical examples of working with REST API on the mobile application side. As an example, let us take an API for working with orders in an online store. For each HTTP method, a request and expected server response are shown. The examples demonstrate the typical RESTful API structure used in mobile development.

GET — retrieving a list of orders

A request to retrieve all user orders with pagination. The response contains an array of order objects and meta-information for page navigation. The page and per_page parameters are passed via query string.

// Retrofit Interface for 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 — creating a new order

Creating a new order via a POST request. The server returns a 201 Created status and the created object in the response body. Important: creation is done on the collection /api/v1/orders, not on a specific resource — this is the standard RESTful pattern.

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

// Example Request Body
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — deleting an order

Deleting a resource is done with the DELETE method on the specific order URL. Successful deletion returns 204 No Content. The idempotence of DELETE means that a repeated request to the same URL returns 404 Not Found, which is handled correctly on the client side.

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

// Usage in ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

These examples demonstrate a typical REST API implementation on the Android side using Retrofit and Kotlin Coroutines. For iOS applications, URLSession or the Alamofire library paired with Codable protocols serve a similar role. The REST API structure remains the same regardless of the platform — only the method of making requests changes.

RESTful API Design: Practical Recommendations

Designing a high-quality RESTful API requires following conventions that make the API intuitive for developers. Resources should be named with plural nouns (/users, /orders, /products), HTTP methods should reflect operations, and URLs should represent nesting hierarchy. Errors should return a standardized JSON with a code and message, not just an HTTP status. Following these conventions lowers the entry barrier for new developers and simplifies integration.

• Resource naming — plural, kebab-case: /api/v1/user-orders, not /api/v1/getUserOrders
• Filtering and sorting — via query parameters: ?status=active&sort=created_at:desc
• Pagination — cursor-based for large datasets, page-based for small ones
• Versioning — via URL (/api/v2/) or Accept-Version header
• Errors — unified format: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — X-RateLimit-Remaining and Retry-After headers

One common mistake when designing a REST API is excessive resource nesting. Instead of /users/1/orders/5/items/3, it is better to use a flat structure with query parameters: /items?order_id=5&user_id=1. This simplifies caching, does not require maintaining long paths on the server, and is easier to document. Flat architecture also has better compatibility with graph-based queries when migrating to GraphQL in the future.

REST API security is implemented through authentication (JWT, OAuth 2.0) and authorization at the resource level. Each request must check whether the user has access to the requested resource. HTTPS is mandatory — without encryption, tokens and data are transmitted in plain text. For mobile applications, it is recommended to use OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure token acquisition.

Versioning and Caching

Versioning of REST API is necessary for backward compatibility during changes. The most common approaches are: version in URL (/api/v1/orders), version in header (Accept: application/vnd.myapi.v1+json), and version in query parameter (?api_version=1). URL versioning is the most popular method as it is explicitly visible in logs and documentation. However, it violates the REST principle of a single URL per resource.

Caching in REST API is implemented via HTTP headers Cache-Control, ETag, and Last-Modified. GET requests marked as cacheable can be served from browser or proxy cache without contacting the server. For mobile applications, caching is especially important — it reduces data usage and speeds up displaying previously loaded data under poor connectivity. ETag is a hash of the response content: the client sends it in If-None-Match, and the server returns 304 Not Modified if the data has not changed.

Modern alternatives to REST API include GraphQL (flexible client-side data fetching) and gRPC (binary protocol on HTTP/2 for microservices). However, REST remains the primary standard for public APIs due to its simplicity, universality, and extensive tool support. The choice between REST and alternatives depends on specific project requirements: query complexity, data volume, real-time update needs.