Skip to content

API Documentation

Jump to bottom
Alan Long edited this page Aug 18, 2020 · 13 revisions

Poaster is a RESTful-ish API (with standard exceptions for non-CRUD operations).

Sessions

Users

Personas

Follows

Authentication:

All authenticated endpoints require an Authorization: Bearer <token> header that identifies the logged in user. The only current unauthenticated endpoint is /api/sessions/sign_in, but this will change as we add support for posts, as we want the site accessible to non-logged in users as well for content discovery.

Sessions:

Sign In

  • POST /api/sessions/sign_in
  • Required Headers: None

Response:

{
  "data": {
    "token": "SFMyNTY.g2gDYQFuBgB5dnztcwFiAAFRgA.fzywx25h5Xnvk2kaLChRjqunE_lyesGhKEdfgn7iebw"
  }
}

Sign Out

  • DELETE /api/sessions/sign_out
  • Required Headers: Authorization

Response: 204 No Content

Revoke Session

  • POST /api/sessions/sign_in
  • Required Headers: Authorization

Expected Body:

{
  "revoke_token": "SFMyNTY.g2gDYQFuBgD82cfjcwFiAAFRgA.AqeROqv9rzadR0LNDvxotL-sd68vX0p4MzM9W7ve8Js"
}

Response:

{
  "data": {
    "token": "SFMyNTY.g2gDYQFuBgB5dnztcwFiAAFRgA.fzywx25h5Xnvk2kaLChRjqunE_lyesGhKEdfgn7iebw"
  }
}

Users:

Me

  • GET /api/users/me
  • Required Headers: Authorization

Response:

{
  "data": {
    "user": {
      "email": "alan.d.long@protonmail.com",
      "personas": [
         {
           "background_image_url": "https://pbs.twimg.com/profile_banners/1169316135092858880/1578077577/1500x500",
           "bio": "Software |☝🏻| Weightlifting | Localist | #Bitcoin | Prepper | Politically Weird | Straight Edge",
           "id": 1,
           "inserted_at": "2020-08-12T20:35:09",
           "name": "A.D.🌺",
           "profile_image_url": "https://pbs.twimg.com/profile_images/1266198123082395648/vCntW9rI_400x400.jpg",
           "updated_at": "2020-08-12T20:35:09",
           "username": "TacticalMinivan"
         },
         {
           "background_image_url": null,
           "bio": null,
           "id": 65,
           "inserted_at": "2020-08-14T04:03:00",
           "name": null,
           "profile_image_url": null,
           "updated_at": "2020-08-14T04:03:00",
           "username": "a"
         },
      ],
      "phone": "3142017135"
    }
  }
}

Create User

  • POST /api/users
  • Required Headers: None
  • Notes: This also logs the user in with the provided email and password

Expected Body:

{
  "email": "alan.d.long@pm.me",
  "phone": "3142017135",
  "password": "poaster!2020"
}

Error Response: 400 Bad Request

{
  "errors": {
    "detail": [
      "Email has already been taken"
    ],
  },
  "success": false
}

Success Response: 201 Created

{
  "data": {
    "user": {
      "email": "alan.d.long@pm.me",
      "phone": "3142017135",
      "token": "SFMyNTY.g2gDYRFuBgABQyX9cwFiAAFRgA.bGVodljYfF-7ac-Dm7kDLXy3oUcgXj42azXM-aILWJ0"
    }
  },
  "success": true
}

Personas:

Create Persona

  • POST /api/personas
  • Required Headers: Authorization

Body:

{
  "username": "tacticalminivan"
}

Error Response: 400 Bad Request

{
  "error": {
    "detail": "You have reached your persona limit. Please purchase additional personas if you wish to create more!"
  },
  "success": false
}

Success Response: 201 Created

{
  "persona": {
    "background_image_url":null,
    "bio":null,
    "id":67,
    "inserted_at":"2020-08-14T15:24:10",
    "name":null,
    "profile_image_url":null,
    "updated_at":"2020-08-14T15:24:10",
    "username":"tacticalminivan"
  },
  success":true
}

Get Persona

  • GET /api/personas/:id
  • Required Headers: Authorization

Error Response: 404 Not Found

Success Response: 200 OK

{
  "background_image_url":"https://pbs.twimg.com/profile_banners/1169316135092858880/1578077577/1500x500",
  "bio":"Software |☝🏻| Weightlifting | Localist | #Bitcoin | Prepper | Politically Weird | Straight Edge",
  "id":1,
  "inserted_at":"2020-08-12T20:35:09",
  "name":"A.D.🌺",
  "profile_image_url":"https://pbs.twimg.com/profile_images/1266198123082395648/vCntW9rI_400x400.jpg",
  "updated_at":"2020-08-12T20:35:09",
  "username":"TacticalMinivan"
}

Update Persona

  • PATCH /api/personas/:id
  • Required Headers: Authorization

Body: Acceptable params in persona object: [background_image_url, bio, name, profile_image_url]. Other params will simply be ignored.

{
  "persona": {
    "bio": "My bio"
  }
}

Error Response: 400 Bad Request

Success Response: 201 Created

{
  "persona": {
    "background_image_url": null,
    "bio": "my bio",
    "id": 42,
    "inserted_at": "2020-08-14T01:52:17",
    "name": null,
    "profile_image_url": null,
    "updated_at": "2020-08-14T15:31:59",
    "username": "alandlong"
  },
  "success": true
}

Delete Persona

  • DELETE /api/personas/:id
  • Required Headers: Authorization

Error Response: 404 Not Found

Success Response: 200 OK

{
  "success": true
}

Username Availability

  • POST /api/personas/availability
  • Required Headers: Authorization

Body:

{
  "username": "POTUS"
}

Success Response: 200 OK

{
  "available": true
}

Follows:

Get Follows

  • GET /api/follows
  • Required Headers: Authorization
  • Query params: current_persona_id

Success Response: 200 OK

{
  "follows": [
    {
      "followed_id": 42,
      "followed_persona_details": {
        "bio": "ASDF",
        "name": null,
        "profile_image_url": null,
        "username": "alandlong"
      },
      "id": 1,
      "inserted_at": "2020-08-12T20:35:09"
    }
  ]
}

Follow

  • POST /api/follows
  • Required Headers: Authorization

Body:

{
  "current_persona_id": 1,
  "persona_id": 42
}

Success Response: 200 OK

{
  "success": true
}

Error Response: 500 Internal Server Error

{
  "success": false,
  "error": {
    "detail": "Error following that persona!"
  }
}

Unfollow

  • DELETE /api/follows
  • Required Headers: Authorization

Body:

{
  "current_persona_id": 1,
  "following_id": 5
}

Success Response: 200 OK

{
  "success": true
}

Error Response: 500 Internal Server Error

{
  "success": false,
  "error": {
    "detail": "Error unfollowing that persona!"
  }
}

Clone this wiki locally