Tags do Blog

As tags são etiquetas fundamentais para a organização do conteúdo. Elas permitem que você agrupe posts por tópicos específicos, facilitando a descoberta de conteúdo relacionado pelos leitores e melhorando o SEO do seu blog.

Organização e SEO

Diferente das categorias, que costumam ser amplas, as tags podem ser mais específicas. Use-as para destacar palavras-chave importantes do seu post.

Requisitos de Autenticação

A maioria dos endpoints de tags exige autenticação através de um token Bearer e a identificação do blog via cabeçalho:

• Authorization: Bearer <seu-token>
• X-Blog-Id: <id-do-blog>

O endpoint de Listagem Pública exige apenas o cabeçalho X-Blog-Id.

---

Listar Tags (Privado)

Retorna uma lista paginada de todas as tags cadastradas no blog.

GET /v1/blog/tags

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	Número da página para paginação.
perPage	number	Não	Quantidade de itens por página.
search	string	Não	Filtra tags pelo nome (busca parcial).

Exemplo de Requisição

curl -X GET https://api.us.basis.tavares.in/v1/blog/tags \
  -H "Authorization: Bearer <seu-token>" \
  -H "X-Blog-Id: seu-blog-id"

Resposta de Sucesso 200 OK

{
  "meta": {
    "total": 2,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 1,
    "firstPage": 1,
    "firstPageUrl": "/?page=1",
    "lastPageUrl": "/?page=1",
    "nextPageUrl": null,
    "previousPageUrl": null
  },
  "data": [
    {
      "id": "2",
      "name": "Laravel",
      "createdAt": "2026-03-30T00:29:11.339+00:00",
      "updatedAt": "2026-03-30T00:29:11.339+00:00"
    },
    {
      "id": "1",
      "name": "Vue.js",
      "createdAt": "2026-03-30T00:28:54.676+00:00",
      "updatedAt": "2026-03-30T00:28:54.676+00:00"
    }
  ]
}

---

Listar Tags (Público)

Retorna uma lista simplificada de tags para uso em componentes de frontend (como seletores ou nuvens de tags). Este endpoint não exige autenticação de usuário, apenas a identificação do blog.

GET /v1/blog/tags/public/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Filtra tags pelo nome (busca parcial).

Exemplo de Requisição

curl -X GET https://api.us.basis.tavares.in/v1/blog/tags/public/list \
  -H "X-Blog-Id: seu-blog-id"

Resposta de Sucesso 200 OK

[
  {
    "value": "1",
    "label": "Vue.js"
  },
  {
    "value": "2",
    "label": "Laravel"
  }
]

---

Criar Tag

Cria uma nova tag para o blog.

POST /v1/blog/tags

Parâmetros do Body

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da tag (máx. 100 caracteres). Deve ser único no blog.

Exemplo de Requisição

curl -X POST https://api.us.basis.tavares.in/v1/blog/tags \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <seu-token>" \
  -H "X-Blog-Id: seu-blog-id" \
  -d '{
    "name": "AdonisJS"
  }'

Resposta de Sucesso 201 Created

{
  "id": "3"
}

Respostas de Erro

422 Unprocessable Entity - Erro de Validação

Ocorre quando o nome não é enviado, excede o limite ou já existe no blog.

{
  "errors": [
    {
      "message": "Tag já cadastrada",
      "rule": "database.unique",
      "field": "name"
    }
  ]
}

---

Detalhes da Tag

Recupera as informações de uma tag específica pelo ID.

GET /v1/blog/tags/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	ID único da tag.

Resposta de Sucesso 200 OK

{
  "id": "1",
  "name": "Vue.js",
  "createdAt": "2026-03-30T00:28:54.676+00:00",
  "updatedAt": "2026-03-30T00:28:54.676+00:00"
}

404 Not Found

Se o ID fornecido não existir ou pertencer a outro blog, a API retornará 404.

---

Atualizar Tag

Altera o nome de uma tag existente.

PUT /v1/blog/tags/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	ID único da tag.

Parâmetros do Body

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Novo nome para a tag.

Resposta de Sucesso 204 No Content

A API não retorna corpo em caso de sucesso na atualização.

---

Excluir Tag

Remove permanentemente uma tag do blog.

DELETE /v1/blog/tags/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	ID único da tag.

Resposta de Sucesso 204 No Content

A tag foi removida com sucesso.