Documentação da API Papacapim

Bem-vindo(a) à documentação da API Papacapim. Este documento será seu guia para entender os endpoints da API, ajudando-o a construir um font-end para integração com nosso back-end. Esta documentação está dividida da seguinte maneira:

1. Como acessar a API
2. Autenticação
3. Usuários
4. Seguidores
5. Postagens
6. Curtidas

Em cada tópico da documentação será exibido um exemplo do corpo da requisição e da resposta. As chaves JSON em cada exemplo são auto-explicativas.

O que é a API Papacapim?

É uma API RESTful bem simples que eu criei para que meus alunos pudessem praticar Flutter na disciplina Desenvolvimento Mobile (IFBA). Minha intenção era dar a eles uma API suficiente para que pudessem fazer requisições e produzir assim um front-end, servindo de objeto de avaliação da disciplina.

Baixe o app Android (APK) oficial para ajudar nos testes ou então acesse a versão web.

Como acessar a API

A API Papacapim é aberta e qualquer um pode acessá-la para praticar a criação de front-ends com consumo de APIs através da URL https://api.papacapim.just.pro.br.

Retornar ao início

Autenticação

Todos os endpoints, com exceção do endpoint para criação de um novo usuário, requerem autenticação. Desta forma, apenas usuários autenticados poderão acessar a API e todos os objetos que forem criados serão associados ao usuário autenticado.

A autenticação no Papacapim funciona através de um token de sessão. Este token deverá ser enviado a cada requisição no cabeçalho HTTP através da chave x-session-token. Para obter um token basta criar uma nova sessão usando seu usuário e senha (caso não tenha usuário, crie antes usando o endpoint Criar usuário). Para encerrar a sessão (uma espécie de log-out), basta deletar a sessão previamente criada.

Nova sessão: POST /sessions

Corpo

Objeto JSON contendo login e senha.

    {
      "login": "frankson",
      "password": "123mudar"
    }
  

Resposta: 200

Objeto JSON da sessão criada. Armazene o valor de token para usar nas próximas requisições.

    {
      "user_login": "frankson",
      "token": "12835982-bc61-4f48-9561-ec1471969c6e",
      "ip": "::1",
    }
  

Encerrar sessão: DELETE /sessions/1

Resposta: 204

Sem conteúdo.

Retornar ao início

Usuários

Nos endpoints a seguir trataremos da manipulação de usuários da plataforma. A criação de novos usuários é livre e pode ser feita por qualquer um (este é o único endpoint que não precisa de autenticação). Após criado um usuário você poderá autenticá-lo e acessar os outros endpoints.

Criar usuário: POST /users

Corpo

Um objeto JSON contendo o login, nome, senha e confirmação de senha do novo usuário.

    {
      "user": {
        "login": "frankson",
        "name": "Frankson Barreto",
        "password": "123mudar",
        "password_confirmation": "123mudar"
      }
    }
  

Resposta: 201

O corpo da resposta conterá um JSON do usuário criado.

    {
      "login": "frankson",
      "name": "Frankson Barreto",
      "created_at": "2024-08-03T12:04:12.460Z",
    }
  

Alterar usuário: PATCH /users/1

Corpo

Um objeto JSON contendo o login, nome, senha e confirmação de senha do novo usuário. Neste caso os campos são todos opcionais. Por exemplo: se deseja mudar apenas o login, basta enviar login; se deseja apenas alterar a senha, basta enviar password e password_confirmation. É possível enviar tudo para alterar todos os dados caso queira.

Por razões de segurança, todas as sessões ativas serão excluídas ao alterar a senha e será preciso criar uma nova sessão para continuar acessando a API.

A imagem de perfil do usuário deve ser enviada na codificação Base64 usando o parâmetro image_data no objeto JSON. Caso não seja enviado a imagem de perfil permanecerá inalterada. O tamanho da imagem é limitado a 5 MB.

    {
      "user": {
        "login": "franks",
        "name": "Frankson Batista",
        "password": "senhanova",
        "password_confirmation": "senhanova",
        "image_data": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgK..."
      }
    }
  

Resposta: 200

O corpo da resposta conterá um JSON com os novos dados do usuário.

    {
      "login": "franks",
      "name": "Frankson Batista",
    }
  

Listar usuários: GET /users

Parâmetros de URL

• page: (opcional, inteiro) Determina a página da listagem para evitar que todos os usuários sejam listados ao mesmo tempo.
• search: (opcional, string) Busca usuários pelo nome. Se omitido, retorna todos os usuários cadastrados.

Resposta: 200

O corpo da resposta conterá um JSON com a lista de usuários.

    [
      {
        "login": "just",
        "name": "J. P. Just",
        "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp",
        "followers_number": 15482986,
        "following_number": 1,
        "you_follow": false,
        "follows_you": false
      },
      {
        "login": "teste",
        "name": "Testador",
        "profile_image": "https://api.papacapim.just.pro.br/image/profile/c2182b38-ac70-457d-ba3e-da68dbb3a2f1.webp",
        "followers_number": 0,
        "following_number": 4920,
        "you_follow": false,
        "follows_you": false
      },
      {
        "login": "frankson",
        "name": "Frankson Barreto",
        "profile_image": "https://api.papacapim.just.pro.br/image/profile/2d203ae9-53df-41ed-bcfd-f1054b37524b.webp",
        "followers_number": 120,
        "following_number": 230,
        "you_follow": true,
        "follows_you": true
      }
    ]
  

Obter usuário específico: GET /users/{login}

Parâmetros de URL

• {login}: (string) Login do usuário que deseja obter. Use o login me para pegar seu próprio perfil.

Resposta: 200

O corpo da resposta conterá um JSON com os dados do usuário.

    {
      "login": "just",
      "name": "J. P. Just",
      "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp",
      "followers_number": 15482986,
      "following_number": 1,
      "you_follow": false,
      "follows_you": false
    }
  

Excluir usuário: DELETE /users/me

Resposta: 204

Sem conteúdo.

Retornar ao início

Seguidores

Os endpoints de seguidores permitirão que um usuário siga alguém ou liste os seguidores de alguém.

Seguir alguém: POST /users/{login}/followers

Parâmetros de URL

• {login}: (string): Login do usuário que você deseja seguir.

Resposta: 201

O corpo da resposta conterá um JSON com os dados da relação de seguidor criada.

    {
      "follower_login": "frankson",
    }
  

Listar seguidores: GET /users/{login}/followers

Parâmetros de URL

• {login}: (string) Login do usuário o qual você quer listar os seguidores.

Resposta: 200

O corpo da resposta conterá um JSON com a lista de seguidores deste usuário.

    [
      {
        "follower": {
          "login": "teste",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      },
      {
        "follower": {
          "login": "franks",
          "name": "Frankson Barreto",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/2d203ae9-53df-41ed-bcfd-f1054b37524b.webp"
        }
      }
    ]
  

Deixar de seguir: DELETE /users/{login}/followers/me

Parâmetros de URL

• {login}: (string) Login do usuário o qual você quer deixar de seguir.

Resposta: 204

Sem conteúdo.

Retornar ao início

Postagens

Nos endpoints a seguir trataremos da manipulação de postagens, possibilitando a criação de novas postagens, respostas a postagens de outros usuários e exclusão de postagens.

Nova postagem: POST /posts

Corpo

Um objeto JSON contendo a postagem.

    {
      "post": {
        "message": "Acabei de entrar no Papacapim!"
      }
    }
  

Resposta: 201

O corpo da resposta conterá um JSON com a postagem criada.

    {
      "id": 7,
      "post_id": null,
      "message": "Acabei de entrar no Papacapim!",
      "created_at": "2024-08-03T13:34:18.103Z",
    }
  

Responder uma postagem: POST /posts/{id}/replies

Parâmetros de URL

• {id}: (inteiro) ID da postagem que será respondida.

Corpo

Um objeto JSON contendo a postagem.

    {
      "reply": {
        "message": "Também entrei no Papacapim essa semana. É muito massa!",
      }
    }
  

Resposta: 201

O corpo da resposta conterá um JSON com a postagem criada. Na resposta o campo post_id refere-se ao ID do post que está sendo respondido.

    {
      "id": 8,
      "post_id": 7,
      "message": "Também entrei no Papacapim essa semana. É muito massa!",
      "created_at": "2024-08-03T13:36:56.977Z",
      "likes_number": 0,
      "replies_number": 0,
      "you_liked": false,
      "user": {
        "login": "just",
        "name": "J. P. Just",
        "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
      }
    }
  

Listar postagens e feed: GET /posts

Parâmetros de URL

• page: (opcional, inteiro) Determina a página da listagem para evitar que todos as postagens sejam listadas ao mesmo tempo.
• feed: (opcional, inteiro) Se for 1 lista apenas postagens feitas pelos usuários que você segue.
• search: (opcional, string) Busca mensagens com algum do(s) termo(s) especificado(s).

Resposta: 200

O corpo da resposta conterá um JSON com a lista de postagens.

    [
      {
        "id": 2,
        "post_id": null,
        "message": "Vou passar a usar esta rede.",
        "created_at": "2024-08-01T14:30:33.000Z",
        "likes_number": 3,
        "replies_number": 1,
        "you_liked": false,
        "user": {
          "login": "just",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      },
      {
        "id": 6,
        "post_id": 2,
        "message": "Esta rede é muito massa!",
        "created_at": "2024-08-01T14:31:05.000Z",
        "likes_number": 0,
        "replies_number": 0,
        "you_liked": true,
        "user": {
          "login": "gustavo",
          "name": "Gustavo Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/28fe8656-d6c7-4b25-b00e-42c60af6c8bf.webp"
        }
      },
      {
        "id": 7,
        "post_id": null,
        "message": "Acabei de entrar no Papacapim!",
        "created_at": "2024-08-03T13:34:18.103Z",
        "likes_number": 1,
        "replies_number": 1,
        "you_liked": true,
        "user": {
          "login": "frankson",
          "name": "Frankson Barreto",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/2d203ae9-53df-41ed-bcfd-f1054b37524b.webp"
        }
      },
      {
        "id": 8,
        "post_id": 7,
        "message": "Também entrei no Papacapim essa semana. É muito massa!",
        "created_at": "2024-08-03T13:36:56.977Z",
        "likes_number": 3,
        "replies_number": 0,
        "you_liked": false,
        "user": {
          "login": "just",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      }
    ]
  

Listar postagens do usuário: GET /users/{login}/posts

Parâmetros de URL

• {login}: (string) Determina qual usuário autor das postagens a serem listadas.
• page: (opcional, inteiro) Determina a página da listagem para evitar que todos as postagens sejam listadas ao mesmo tempo.

Resposta: 200

O corpo da resposta conterá um JSON com a lista de postagens.

    [
      {
        "id": 2,
        "post_id": null,
        "message": "Vou passar a usar esta rede.",
        "created_at": "2024-08-01T14:30:33.000Z",
        "likes_number": 0,
        "replies_number": 0,
        "you_liked": false,
        "user": {
          "login": "just",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      },
      {
        "id": 8,
        "post_id": 7,
        "message": "Também entrei no Papacapim essa semana. É muito massa!",
        "created_at": "2024-08-03T13:36:56.977Z",
        "likes_number": 3,
        "replies_number": 0,
        "you_liked": true,
        "user": {
          "login": "just",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      }
    ]
  

Listar respostas: GET /posts/{id}/replies

Parâmetros de URL

• {id}: (inteiro) Determina o ID da postagem da qual serão listadas as respostas.
• page: (opcional, inteiro) Determina a página da listagem para evitar que todos as postagens sejam listadas ao mesmo tempo.

Resposta: 200

O corpo da resposta conterá um JSON com a lista de respostas.

    [
      {
        "id": 8,
        "post_id": 7,
        "message": "Também entrei no Papacapim essa semana. É muito massa!",
        "created_at": "2024-08-03T13:36:56.977Z",
        "likes_number": 3,
        "replies_number": 0,
        "you_liked": true,
        "user": {
          "login": "just",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      }
    ]
  

Excluir postagem: DELETE /posts/{id}

Parâmetros de URL

• id: (inteiro) ID da postagem que deseja excluir.

Resposta: 204

Sem conteúdo.

Retornar ao início

Curtidas

Nos endpoints a seguir trataremos da manipulação de curtidas em uma postagem. Eles permitirão curtir uma postagem, descurtir e visualizar curtidas.

Curtir postagem: POST /posts/{id}/likes

Parâmetros de URL

• id: (inteiro) ID da postagem que deseja curtir.

Resposta: 201

O corpo da resposta conterá um JSON com dados da curtida.

    {
      "user_login": "frankson",
    }
  

Listar curtidas: GET /posts/{id}/likes

Parâmetros de URL

• id: (inteiro) ID da postagem que deseja visualizar curtidas.

Resposta: 200

O corpo da resposta conterá um JSON com a lista de curtidas.

    [
      {
        "user": {
          "login": "teste",
          "name": "J. P. Just",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/fa87ebb3-ef93-48d6-b437-2c4bdbbd0686.webp"
        }
      },
      {
        "user": {
          "login": "franks",
          "name": "Frankson Barreto",
          "profile_image": "https://api.papacapim.just.pro.br/image/profile/2d203ae9-53df-41ed-bcfd-f1054b37524b.webp"
        }
      }
    ]
  

Remover curtida: DELETE /posts/{id}/likes/me

Parâmetros de URL

• id: (inteiro) ID da postagem que deseja descurtir.

Resposta: 204

Sem conteúdo.

Retornar ao início