Jobfeed users API🔗
All the requests and responses will be sent over HTTP.
All the requests must contain authentication information (Basic HTTP
authentication). If the authentication information is missing or incorrect you
will receive a 401 Unauthorized response.
All the requests and responses will be in JSON format.
There are two types or URLs:
* The collection URL (/api/users/) that allows you to get the user list and
add new users
* The user URL (/api/users/1234 - where 1234 is the user ID) that allows you
to retrieve user information, modify and delete the user
Getting a list of users🔗
Endpoint: /api/users/
Method: GET
Returns the user list (each with username and URL). The HTTP status code will always be 200 (OK)
Example:
> GET /api/users/ HTTP/1.1
> Authorization: Basic am9obmRvZTpwYXNzd29yZA==
> Host: www.jobfeed.nl
>
< HTTP/1.0 200 OK
< Content-Type: application/json
<
< [{"username":"foo","reference":"http:\/\/www.jobfeed.nl\/api\/users\/1232"},{"username":"bar","reference":"http:\/\/www.jobfeed.nl\/api\/users\/1233"}]
Creating a new user🔗
Endpoint: /api/users/
Method: POST
Creates a new user. It expects a JSON object with the following fields:
| Field | Type | Comment |
|---|---|---|
| username | string | required |
| password | string | required |
| string | required | |
| description | string | optional |
| comment | string | optional |
| expiration_date | string | optional; in the yyyy-mm-dd format |
| privileges | object | optional; can have two boolean fields: analytics and excel_reporting |
The Content-Type of the request must be application/json.
In case of success the HTTP status code will be 201 (Created) and there will be a Location header with the URL of the newly created user. If there is something wrong with the request the HTTP status code will be 400 (Bad Request) and the body of the response will contain a description of the problem. If a user with the same username already exists the HTTP status code will be 409 (Conflict). If you have already added the maximum number the users allowed or if you are trying to give the new user a privilege that it cannot have (because of a limit on the number of users that can have it), the HTTP status code will be 403 (Forbidden).
Example:
> POST /api/users/ HTTP/1.1
> Authorization: Basic am9obmRvZTpwYXNzd29yZA==
> Host: www.jobfeed.nl
> Content-Type: application/json
>
> {"username":"baz","password":"bazpass","email":"baz@example.com","privileges":{"analytics":true}}
>
< HTTP/1.0 201 Created
< Location: http://www.jobfeed.nl/api/users/1234
Getting information about a user🔗
Endpoint: /api/users/1234
Method: GET
Returns information about the user. The HTTP status code will be 200 (OK) if the user exists and 404 (Not Found) otherwise.
Example:
> GET /api/users/1234 HTTP/1.1
> Authorization: Basic am9obmRvZTpwYXNzd29yZA==
> Host: www.jobfeed.nl
>
< HTTP/1.0 200 OK
< Content-Type: application/json
<
< {"username":"baz","email":"baz@example.com","description":"","comment":"","expiration_date":null,"privileges":{"analytics":true,"excel_reporting":false}}
Deleting a user🔗
Endpoint: /api/users/1234
Method: DELETE
Deletes the user. The HTTP status code will be 200 (OK) if the user exists and 404 (Not Found) otherwise.
Example:
> DELETE /api/users/1234 HTTP/1.1
> Authorization: Basic am9obmRvZTpwYXNzd29yZA==
> Host: www.jobfeed.nl
>
< HTTP/1.0 200 OK
Modifying a user🔗
Endpoint: /api/users/1234
Method: PATCH
Modifies a user. It expects a JSON object similar to the POST on
the collection (see above), except all the fields are optional (you
can specify only what changes). You can clear the expiration_date by
setting a null value. The Content-Type of the request
must be application/json. If there is something wrong with the
request the HTTP status code will be 400 (Bad Request) and the body
of the response will contain a description of the problem.
Otherwise the HTTP status code will be 200 (OK) for success,
404 (Not Found) if the user does not exists, 409 (Conflict) if
you attempt to change the username to the username of another
existing user or 403 (Forbidden) if you are trying to give the
user a privilege it cannot have (because of a limit on the number
of users that can have it).
Example:
> PATCH /api/users/1233 HTTP/1.1
> Authorization: Basic am9obmRvZTpwYXNzd29yZA==
> Host: www.jobfeed.nl
> Content-Type: application/json
>
> {"username":"test"}
>
< HTTP/1.0 200 OK