Podling API Documentation

User

Creating Users

Example: Creating Users considers a 4 character password too short.

Request
POST /api/v1/users HTTP/1.1
Host: podling.com
Content-Type: application/json; charset=utf-8

{
  "name": "John",
  "password": "ab12"
}
Reponse
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Content-Length: 133

{
  "message": "Validation failed.",
  "errors": [
    {
      "resource": "User",
      "field": "password",
      "message": "is too short (minimum is 8 characters)"
    }
  ]
}
Back to top

Example: Creating Users creates a user and accepts and returns an email.

Request
POST /api/v1/users HTTP/1.1
Host: podling.com
Content-Type: application/json; charset=utf-8

{
  "name": "John Citizen",
  "email": "john@example.com",
  "password": "test1234"
}
Reponse
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
ETag: "537850bdccb477e6991818ba3315e928"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 389

{
  "id": 3240,
  "name": "John Citizen",
  "email": "john@example.com",
  "avatar_url": null,
  "twitter_username": null,
  "profile": null,
  "location": null,
  "created_at": "2013-02-28T07:19:25Z",
  "url": "http://www.example.com/api/v1/users/3240",
  "access_tokens": [
    {
      "created_at": "2013-02-28T07:19:25Z",
      "id": 1033,
      "token": "OmPA3LxyA0iLMINmrjaCroQNG2uky0XEku8YyLGm1f4",
      "updated_at": "2013-02-28T07:19:25Z",
      "user_id": 3240
    }
  ]
}
Back to top

Listing Users

Example: Listing Users authenticated as User for Group where User is a member lists the members of a group.

Request
GET /api/v1/groups/1598-group-82/members HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken63
Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
ETag: "33bb371d25484afc25273bcf9f5ebc1a"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 657

[
  {
    "id": 3146,
    "name": "OAuth user",
    "email": "user152@example.org",
    "avatar_url": null,
    "twitter_username": null,
    "profile": null,
    "location": null,
    "created_at": "2013-02-28T07:19:20Z",
    "url": "http://www.example.com/api/v1/users/3146"
  },
  {
    "id": 3147,
    "name": "User 117",
    "email": "user153@example.org",
    "avatar_url": null,
    "twitter_username": null,
    "profile": null,
    "location": null,
    "created_at": "2013-02-28T07:19:20Z",
    "url": "http://www.example.com/api/v1/users/3147"
  },
  {
    "id": 3148,
    "name": "User 118",
    "email": "user154@example.org",
    "avatar_url": null,
    "twitter_username": null,
    "profile": null,
    "location": null,
    "created_at": "2013-02-28T07:19:20Z",
    "url": "http://www.example.com/api/v1/users/3148"
  }
]
Back to top

Showing Users

Example: Showing Users as the authenticated user behaves like authorized to show users shows user details excluding access_token.

Request
GET /api/v1/users/3253 HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken116
Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
ETag: "1dea32a1ce100056da47381afc806335"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 219

{
  "id": 3253,
  "name": "OAuth user",
  "email": "user255@example.org",
  "avatar_url": null,
  "twitter_username": null,
  "profile": null,
  "location": null,
  "created_at": "2013-02-28T07:19:26Z",
  "url": "http://www.example.com/api/v1/users/3253"
}
Back to top

Updating Users

Example: Updating Users authenciated as the same User updates user details.

Request
POST /api/v1/users/3257 HTTP/1.1
X-Http-Method-Override: PATCH
Host: podling.com
Authorization: Bearer accesstoken121
Content-Type: application/json; charset=utf-8

{
  "name": "Sonmi~451 ",
  "email": "sonmi@example.org",
  "password": "changedpass",
  "profile": "Ascended server",
  "location": "Nea So Copros"
}
Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
ETag: "44c38dad0db8a574aad71704fdbd2e34"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 303

{
  "id": 3257,
  "name": "Sonmi~451 ",
  "email": "sonmi@example.org",
  "avatar_url": "https://api.twitter.com/1/users/profile_image/oldtwitter",
  "twitter_username": "oldtwitter",
  "profile": "Ascended server",
  "location": "Nea So Copros",
  "created_at": "2013-02-28T07:19:26Z",
  "url": "http://www.example.com/api/v1/users/3257"
}
Back to top

User authentication

Example: User authentication with correct email and password responds 200 OK with user and user_access_token.

Request
POST http://www.example.com/api/v1/users/authenticate HTTP/1.1
Host: podling.com
Content-Type: application/json; charset=utf-8

{
  "email": "user238@example.org",
  "password": "covert12"
}
Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
ETag: "679fb331863fdb2f43fb9d7ca59433b4"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 263

{
  "user": {
    "id": 3232,
    "name": "User 167",
    "email": "user238@example.org",
    "avatar_url": null,
    "twitter_username": null,
    "profile": null,
    "location": null,
    "created_at": "2013-02-28T07:19:24Z",
    "url": "http://www.example.com/api/v1/users/3232"
  },
  "user_access_token": "accesstoken103"
}
Back to top