Table Of Contents

Previous topic

Resources

People

Add, remove, or update the entry for a given person.

GET

DESCRIPTION
Retrieve information on a given person.
URL STRUCTURE
https://www.example.com/<version>/people/<name>
version:API version.
name:Name of the person
VERSIONS
v1
ERRORS
404:No user of that name
EXAMPLES

PUT

DESCRIPTION
Create a new person. Also overwrites an existing person of that name.

URL STRUCTURE

https://www.example.com/<version>/people/<name>
version:API version.
name:Name of the person
VERSIONS
v1
ERRORS
200 - Ok
404 - No user of that name
EXAMPLE

PATCH

DESCRIPTION
Update a new person.

URL STRUCTURE

https://www.example.com/<version>/people/<name>
version:API version.
name:Name of the person
VERSIONS
v1
ERRORS
200 - Ok
404 - No user of that name
EXAMPLE

DELETE

DESCRIPTION
Delete the entry for a specific person.
URL STRUCTURE
https://www.example.com/<version>/people/<name>
version:API version.
name:Name of the person
VERSIONS
v1
ERRORS
404:No user of that name
EXAMPLE

DELETE (all people)

DESCRIPTION
Delete entries for everyone.
URL STRUCTURE
https://www.example.com/<version>/people
version:API version.
VERSIONS
v1
ERRORS
(none)
EXAMPLE

Examples

GET unknown person

$ http --pretty all -jv GET localhost:5000/v1/people/nobody
GET /v1/people/nobody HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 404 NOT FOUND
Content-Length: 184
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:02 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "message": "Person does not exist", 
    "status": "error", 
    "status_code": 404, 
    "status_long_message": "Nothing matches the given URI", 
    "status_short_message": "Not Found"
}

PUT then GET

$ http --pretty all -jv PUT localhost:5000/v1/people/tim email="a@b.c"; echo "\n"; http --pretty all -jv GET localhost:5000/v1/people/tim
PUT /v1/people/tim HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:5000
User-Agent: HTTPie/0.3.0

{
    "email": "a@b.c"
}

HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:02 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "status": "ok"
}

GET /v1/people/tim HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 200 OK
Content-Length: 103
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:03 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "result": {
        "comment": null, 
        "email": "a@b.c", 
        "name": "tim"
    }, 
    "status": "ok"
}

PATCH then GET

$ http --pretty all -jv PATCH localhost:5000/v1/people/tim comment="hello world"; echo "\n"; http --pretty all -jv GET localhost:5000/v1/people/tim
PATCH /v1/people/tim HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:5000
User-Agent: HTTPie/0.3.0

{
    "comment": "hello world"
}

HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:03 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "status": "ok"
}

GET /v1/people/tim HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 200 OK
Content-Length: 112
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:03 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "result": {
        "comment": "hello world", 
        "email": "a@b.c", 
        "name": "tim"
    }, 
    "status": "ok"
}

DELETE person

Note that the second DELETE fails.

$ http --pretty all -jv DELETE localhost:5000/v1/people/tim; echo "\n"; http --pretty all -jv DELETE localhost:5000/v1/people/tim
DELETE /v1/people/tim HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:03 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "status": "ok"
}

DELETE /v1/people/tim HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 404 NOT FOUND
Content-Length: 184
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:03 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "message": "Person does not exist", 
    "status": "error", 
    "status_code": 404, 
    "status_long_message": "Nothing matches the given URI", 
    "status_short_message": "Not Found"
}

DELETE all

$ http --pretty all -jv DELETE localhost:5000/v1/people
DELETE /v1/people HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/json
Date: Tue, 06 Nov 2012 13:40:03 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "status": "ok"
}

Redirect to documentation

A GET with an HTTP Accept Header preferring HTML over JSON will redirect to the on-line documentation.

$ http --pretty all -v GET localhost:5000/v1/people
GET /v1/people HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate, compress
Host: localhost:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 302 FOUND
Content-Length: 259
Content-Type: text/html; charset=utf-8
Date: Tue, 06 Nov 2012 13:40:03 GMT
Location: http://localhost:5000/static/apidocs/people.html
Server: Werkzeug/0.8.3 Python/2.7.3

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to target URL: <a href="static/apidocs/people.html">static/apidocs/people.html</a>.  If not click the link.