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 {token}
• X-Blog-Id: {blog-id} (UUID)

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

---

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: {blog-id}"

Respostas

200 OK

Retorna um array de opções no formato value/label.

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

---

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 (mínimo: 1).
perPage	number	Não	Quantidade de itens por página (mínimo: 1, máximo: 100).
search	string	Não	Filtra tags pelo nome, busca parcial (máx. 150 caracteres).
orderBy	enum	Não	Campo de ordenação: id, name ou createdAt.
orderDirection	enum	Não	Direção da ordenação: asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/blog/tags?page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "X-Blog-Id: {blog-id}"

Respostas

200 OK

Retorna a lista de tags com os metadados de paginação.

{
  "meta": {
    "currentPage": "1",
    "perPage": "25"
  },
  "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"
    }
  ]
}

---

Criar Tag

Cria uma nova tag para o blog. O nome deve ser único dentro do 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 {token}" \
  -H "X-Blog-Id: {blog-id}" \
  -d '{
    "name": "AdonisJS"
  }'

Respostas

201 Created

Retorna o ID da tag criada.

{
  "id": "3"
}

422 Unprocessable Entity

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.

Respostas

200 OK

Retorna o objeto completo da tag.

{
  "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. O novo nome também deve ser único no blog.

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 (máx. 100 caracteres).

Exemplo de Requisição

curl -X PUT https://api.us.basis.tavares.in/v1/blog/tags/2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -H "X-Blog-Id: {blog-id}" \
  -d '{
    "name": "Laravel 12"
  }'

Respostas

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.

Exemplo de Requisição

curl -X DELETE https://api.us.basis.tavares.in/v1/blog/tags/4 \
  -H "Authorization: Bearer {token}" \
  -H "X-Blog-Id: {blog-id}"

Respostas

204 No Content

A tag foi removida com sucesso. A resposta não contém corpo.