Question

I’m building a RESTful API, part of which will be checking if a user has a valid subscription. I’m thinking of doing it like this:

GET https://api.example.org/subscriptions/me?username=johndoe&password=abc123&apikey=somekey HTTP/1.1
Host: api.example.org
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "johndoe",
    "id": 5152,
    "valid": true,
    "valid_until": "2013-01-01 00:00:00",
    "account_level": "basic"
}

The system would return the following status codes:

• 200 if the user has a valid subscription
• 400 if the username or password parameters were omitted
• 401 if the user credentials are invalid
• 402 if the user doesn’t have a valid subscription.
• 403 if the user’s API key is invalid
• 404 if it’s an invalid user
• 429 if the client has made too many API requests

Is this a RESTful API design? Could it be done better? Is HTTP 403 a good response for invalid API keys?

Answer 1

I personally would base everything around the user. The user has a subscription.

I would recommend not passing the password in a GET request. Nobody likes to have a plaintext password stored in their history. You should do a POST /login and set the appropriate session so authentication does not need to happen with each request. If you want it to be completely stateless use basic HTTP authentication.

Request:

GET /users/5152
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Response Body:

{
    "username": "johndoe",
    "password": "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890c"
    "id": 5152,
    "valid": true,
    "valid_until": "2013-01-01 00:00:00",
    "account_level": "basic"
} 

Status Codes:

• 200 if the user exists. Check the subscript status client side.
• 401 if the username or password parameters were omitted
• 401 if the user credentials are invalid
• — if the user doesn’t have a valid subscription. Error on client side
• 404 if the user does not exist
• 429 if the client has made too many API requests