Introduction to REST API Design and Security Practices

REST (Representational State Transfer) is a stateless architectural style built on the HTTP protocol; it does not provide built‑in security, so HTTPS should be used for all requests and security mechanisms must be implemented by developers.

Typical HTTP methods and their actions are: GET – retrieve resource information (e.g., http://xx.com/api/orders); GET with an identifier – retrieve a specific resource (e.g., http://xx.com/api/orders/123); POST – create a new resource; PUT – update an existing resource; DELETE – remove a resource.

Request bodies are usually expressed in JSON (preferred over XML).

Authentication methods covered include:

HTTP Basic : credentials are base64‑encoded and placed in the Authorization header. Example:

base64 before: Basic admin:admin
base64 after: Basic YWRtaW46YWRtaW4=
Header: Authorization: Basic YWRtaW46YWRtaW4=

Because the credentials are only base64‑encoded, SSL/TLS must be enforced.

API Key : after a user authenticates, the server issues an API key, e.g., http://example.com/api?key=dfkaj134. The client combines the api_key, security_key, a timestamp, and the request URI, then generates an HMAC‑SHA256 signature to include in the request URL. The server validates the key, timestamp, and signature to prevent replay attacks and tampering.

OAuth 1.0a / OAuth 2.0 and JWT are mentioned as more secure but complex alternatives; JWT provides a compact, URL‑safe JSON object that can be placed in the Authorization header.

Authorization is illustrated with a PHP role‑based array example:

$roles = array(
    'ADMIN' => array(
        'permit' => array('/^((\/system\/(clouds|device)$/'),
        'deny'   => array('/^(\/system\/audit)$/')
    ),
    'AUDIT' => array(
        'permit' => array('/^(\/system\/audit)$/'),
        'deny'   => array('/^((\/system\/(clouds|device).*)$/')
    )
);

Before business logic, URLs should be filtered, e.g., /site/{num}/policy where {num} must be an integer; requests not matching a whitelist are rejected.

All sensitive traffic should be encrypted with SSL/TLS, especially for critical functions such as certificate handling and configuration backups.

Rate limiting can be implemented per API key or user using an in‑memory store (Redis, Memcached). A PHP example using Laravel‑style filters:

Route::filter('api.limit', function() {
    $key = sprintf('api:%s', Auth::user()->api_key);
    Cache::add($key, 0, 60);
    $count = Cache::increment($key);
    if ($count > Config::get('api.requests_per_hour')) {
        App::abort(403, 'Hourly request limit exceeded');
    }
});

Error handling should return consistent JSON structures for client errors (400 series) and server errors (500 series), e.g., {"result":"Invalid URL!"}, {"result":"json format error"}, {"result":"Method Not Allowed"}. Multi‑status responses (HTTP 207) can convey partial successes and failures.

To prevent ID enumeration, expose opaque identifiers (Base62 or UUID) instead of sequential numeric IDs.

Additional recommendations include always using JSON for request/response bodies, setting Content‑Type: application/json; charset="UTF-8", validating and sanitizing JSON after decoding, enforcing SSL/TLS for all communications, and storing sensitive data (e.g., passwords) as hashed values.

Source: http://drops.wooyun.org/web/9737