Skip to content

REST API example

Jump to bottom
epicmonkey edited this page Jul 2, 2014 · 27 revisions

Sessions

1. Authentication

$ curl -d "username=test" -d "password=test" http://localhost:3000/v1/session
{
  "err": null,
  "status": "success",
  "user": {
    "id": "ecad21a5-45be-4eb8-9398-db51415992fb",
    "username": "test",
    "info": {
      "screenName": "test",
      "email": "[email protected]",
      "receiveEmails": "0"
    }
  }
}

2. Registration

$ curl -d "username=test" -d "password=test" http://localhost:3000/v1/signup
{
  "err": null,
  "status": "success",
  "user": {
    "id": "f6f55f5d-c0b5-4fae-92e8-4d12b84fbe2d",
    "username": "test",
    "info": {
      "screenName": "test"
    }
  }
}

By default an unauthenticated user is an anonymous user and it cannot edit, delete its posts, comments and personal information, so in the examples below I'm assuming cookie connect.sid is set to a current session. (e.g. -b "cookie.sid=your_cookie_here".)

Post

1. Create new post

$ curl -d "body=test2" http://localhost:3000/v1/posts
{
  "id": "237318ed-0c51-4c0a-9be8-2904d3458ce8",
  "body": "test2",
  "createdAt": 1380397179394,
  "updatedAt": 1380397179394,
  "comments": [],
  "attachments": [],
  "likes": [],
  "createdBy": {
    "id": "0aeb1250-7686-43b6-be15-35b7cede21b4",
    "username": "test",
    "info": {
      "screenName": "test"
    }
  },
  "groups": [
    {
      "id": "0aeb1250-7686-43b6-be15-35b7cede21b4",
      "username": "test",
      "info": {
        "screenName": "test"
      }
    }
  ]
}

2. Read post

$ curl http://localhost:3000/v1/posts/237318ed-0c51-4c0a-9be8-2904d3458ce8
{
  "id": "237318ed-0c51-4c0a-9be8-2904d3458ce8",
  "body": "test2",
  "createdAt": 1380397179394,
  "updatedAt": 1380397179395,
  "comments": [],
  "attachments": [],
  "likes": [],
  "createdBy": {
    "id": "0aeb1250-7686-43b6-be15-35b7cede21b4",
    "username": "test3",
    "info": {
      "screenName": "test3"
    }
  },
  "groups": [
    {
      "id": "0aeb1250-7686-43b6-be15-35b7cede21b4",
      "username": "test3",
      "info": {
        "screenName": "test3"
      }
    }
  ]
}

3. Update post

$ curl -d "body=test" -X PATCH http://localhost:3000/v1/posts/237318ed-0c51-4c0a-9be8-2904d3458ce8
{}

4. Delete post

$ curl -X DELETE http://localhost:3000/v1/posts/237318ed-0c51-4c0a-9be8-2904d3458ce8
{}

5. Like post

$ curl -X POST http://localhost:3000/v1/posts/b03fb549-7e49-4c3d-af88-12525ec32984/like
{}

6. Unlike post

$ curl -X POST http://localhost:3000/v1/posts/b03fb549-7e49-4c3d-af88-12525ec32984/unlike
{}

Comments

1. Add new comment

$ curl -d "postId=b03fb549-7e49-4c3d-af88-12525ec32984" -d "body=comment" http://localhost:3000/v1/comments
{
  "id": "c2ce761f-6147-4c1d-b0ad-2c14c89292a1",
  "body": "comment",
  "postId": "b03fb549-7e49-4c3d-af88-12525ec32984",
  "createdAt": 1380397766986,
  "updatedAt": 1380397766986,
  "createdBy": {
    "id": "135b41b3-8193-4612-be7c-38e058a073b6",
    "username": "anonymous",
    "info": {
      "screenName": "anonymous"
    }
  }
}

2. Update comment

$ curl -X PATCH -d "body=test" http://localhost:3000/v1/comments/984a2f8f-c0e8-4b15-8f4e-e74d353210fc
{}

3. Delete comment

$ curl -X DELETE http://localhost:3000/v1/comments/984a2f8f-c0e8-4b15-8f4e-e74d353210fc
{}

Timeline

1. Get user timeline

$ curl http://localhost:3000/v1/timeline/anonymous
{
  "id": "0f8320aa-a31a-4edc-9bab-3643fd92c1ef",
  "name": "Posts",
  "user": {
    "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
    "username": "anonymous",
    "type": "user",
    "info": {
      "screenName": "anonymous"
    },
    "statistics": {
      "userId": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
      "posts": "1",
      "likes": "0",
      "discussions": "0",
      "subscribers": "1",
      "subscriptions": "1"
    },
    "subscribers": [
      {
        "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
        "username": "test"
      }
    ],
    "subscriptions": [
      {
        "id": "e959db46-c2a5-4fee-95be-5f0aed0134a9",
        "name": "Posts",
        "user": {
          "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
          "username": "test"
        }
      },
      {
        "id": "9b884493-8ec0-4fc6-8432-946e676aa660",
        "name": "Likes",
        "user": {
          "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
          "username": "test"
        }
      },
      {
        "id": "4cd94d9e-4f2e-4682-b17f-3b04b6737133",
        "name": "Comments",
        "user": {
          "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
          "username": "test"
        }
      }
    ]
  },
  "posts": [
    {
      "id": "88699b63-48b9-4ca5-b4f8-02909b3f4507",
      "body": "Hello world",
      "createdAt": 1380398266250,
      "updatedAt": 1380398266250,
      "comments": [],
      "attachments": [],
      "likes": [],
      "createdBy": {
        "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
        "username": "anonymous",
        "info": {
          "screenName": "anonymous"
        }
      },
      "groups": [
        {
          "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
          "username": "anonymous",
          "info": {
            "screenName": "anonymous"
          }
        }
      ]
    }
  ],
  "subscribers": [
    {
      "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
      "username": "test"
    }
  ]
}

2. List of subscribers to a timeline

$ curl http://localhost:3000/v1/timeline/0f8320aa-a31a-4edc-9b-3643fd92c1ef/subscribers
[
  {
    "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
    "username": "test",
    "info": {
      "screenName": "test"
    }
  }
]

3. Subscribe to a timeline

curl -X POST http://localhost:3000/v1/timeline/e959db46-c2a5-4fee-95be-5f0aed0134a9/subscribe
{
  "err": null,
  "status": "success"
}

4. Unsubscribe to a timeline

curl -X POST http://localhost:3000/v1/timeline/e959db46-c2a5-4fee-95be-5f0aed0134a9/unsubscribe
{
  "err": null,
  "status": "success"
}

Users and groups

1. Get current user info

$ curl http://localhost:3000/v1/whoami
{
  "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
  "username": "anonymous",
  "type": "user",
  "info": {
    "screenName": "anonymous"
  },
  "rss": []
}

2. Get user info

$ curl http://localhost:3000/v1/users/0b1bd0dc-9f10-4002-bcff-cc7e6e8c02e
{
  "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
  "username": "anonymous",
  "type": "user",
  "info": {
    "screenName": "anonymous"
  },
  "rss": []
}

3. Get user subscriptions

$ curl http://localhost:3000/v1/users/anonymous/subscriptions
[
  {
    "id": "e959db46-c2a5-4fee-95be-5f0aed0134a9",
    "name": "Posts",
    "user": {
      "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
      "username": "test",
      "type": "user",
      "info": {
        "screenName": "test"
      }
    }
  },
  {
    "id": "9b884493-8ec0-4fc6-8432-946e676aa660",
    "name": "Likes",
    "user": {
      "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
      "username": "test",
      "type": "user",
      "info": {
        "screenName": "test"
      }
    }
  },
  {
    "id": "4cd94d9e-4f2e-4682-b17f-3b04b6737133",
    "name": "Comments",
    "user": {
      "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
      "username": "test",
      "type": "user",
      "info": {
        "screenName": "test"
      }
    }
  }
]

4. Get user's subscribers

$ curl http://localhost:3000/v1/users/anonymous/subscribers
{
  "subscribers": [
    {
      "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
      "username": "test",
      "info": {
        "screenName": "test"
      }
    }
  ]
}

5. Unsubscribe user from a user or a group

$ curl -X DELETE http://localhost:3000/v1/users/anonymous/subscribers/fa7d253f-7a70-452f-924b-bda7953a5321
{
  "err": null,
  "status": "success"
}

6. Give user group admin righs

$ curl -X POST http://localhost:3000/v1/users/group/subscribers/fa7d253f-7a70-452f-924b-bda7953a5321/admin
{
  "err": null,
  "status": "success"
}

7. Remove admin rights

$ curl -X POST http://localhost:3000/v1/users/group/subscribers/fa7d253f-7a70-452f-924b-bda7953a5321/unadmin
{
  "err": null,
  "status": "success"
}

8. Delete group (users for the time being are permanent)

$ curl -X DELETE http://localhost:3000/v1/users/2f4d64f5-5c3a-4dfd-8a16-fd894e9aa9a5
{
  "err": null,
  "status": "success"
}

9. Update user info

$ curl -X PATCH -d "params[email][email protected]" -d "params[screenName]=newTest" -d "params[receiveEmails]=1" -d "params[rss[]]=http://rss" -d "params[userId]=fa7d253f-7a70-452f-924b-bda7953a5321" http://localhost:3000/v1/users
{
  "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
  "username": "test",
  "type": "user",
  "info": {
    "screenName": "test",
    "email": "[email protected]",
    "receiveEmails": "1"
  },
  "rss": [
    "http://rss"
  ]
}

Stats

1. Get top users who likes more than other

$ curl http://localhost:3000/v1/top/likes
[
  {
    "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
    "username": "test",
    "info": {
      "screenName": "test",
      "email": "[email protected]",
      "receiveEmails": "0"
    },
    "score": "0"
  },
  {
    "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
    "username": "anonymous",
    "info": {
      "screenName": "anonymous"
    },
    "score": "0"
  }
]

Tags

1. Get tags sorted by frequency

$ curl http://localhost:3000/v1/tags
[
  "#world",
  "#hello"
]

Search

1. Simple search by a keyword

$ $ curl http://localhost:3000/v1/search/hel
{
  "posts": [
    {
      "id": "88699b63-48b9-4ca5-b4f8-02909b3f4507",
      "body": "Hello world",
      "createdAt": 1380398266250,
      "updatedAt": 1380398266250,
      "groups": [],
      "comments": [],
      "attachments": [],
      "likes": [],
      "createdBy": {
        "id": "0b1bd0dc-9f10-4002-bcff-3cc7e6e8c02e",
        "username": "anonymous",
        "info": {
          "screenName": "anonymous"
        }
      }
    },
    {
      "id": "4163f133-a580-4bbf-a59e-97825e3762fa",
      "body": "#hello",
      "createdAt": 1380400485640,
      "updatedAt": 1380400485641,
      "groups": [],
      "comments": [],
      "attachments": [],
      "likes": [],
      "createdBy": {
        "id": "fa7d253f-7a70-452f-924b-bda7953a5321",
        "username": "test",
        "info": {
          "screenName": "test",
          "email": "[email protected]",
          "receiveEmails": "0"
        }
      }
    }
  ]
}
Clone this wiki locally