{}JSON Dock

Guia de primeiros passos

Do cadastro ao primeiro registro em minutos.

Sete passos curtos, com exemplos em SDK JavaScript e cURL. Para a lista completa de parâmetros e operadores, veja a referência da API.

Criar projeto grátisReferência da API
Antes de continuar: o JSON Dock é gratuito e best-effort. Mantenha uma cópia dos dados importantes e nunca exponha credenciais Basic em um site público.

Passo 1

Crie um projeto gratuito

Preencha o cadastro na página inicial. Ao concluir, você recebe o slug, o usuário e uma senha de 32 caracteres. A senha aparece apenas uma vez — copie antes de fechar.

Ir para o cadastro

Passo 2

Baixe o SDK JavaScript

O SDK não tem dependências. Salve o arquivo como src/lib/json-dock-client.js no seu projeto. Se preferir usar fetch ou cURL direto, pule para o passo 3 — todos os exemplos têm as duas versões.

Baixar json-dock-client.js

Passo 3

Configure as credenciais

Substitua os três valores pelas credenciais recebidas. Basic Auth é indicado para estudos, scripts locais e backends privados.

src/api.js
import { JsonDockClient, JsonDockApiError } from './lib/json-dock-client.js';

export const api = new JsonDockClient({
  baseUrl: 'https://api.jsondock.catini.org',
  projectSlug: 'SEU_SLUG',
  basicAuth: {
    username: 'SEU_USUARIO',
    password: 'SUA_SENHA',
  },
});
Credenciais no frontendTodo código enviado ao navegador pode ser lido pelo visitante. Em sites públicos, mantenha Basic Auth no seu backend e encaminhe as operações, ou use tokens Bearer de curta duração via OAuth 2.0.

Passo 4

Grave o primeiro registro

O namespace produtos nasce automaticamente no primeiro POST. O objeto pode ter os campos que fizerem sentido — não há schema para declarar.

const produto = await api.create('produtos', {
  nome: 'Teclado mecanico',
  preco: 349.9,
  estoque: 12,
  ativo: true,
  categoria: 'perifericos',
});

console.log('Produto criado:', produto.id);

Passo 5

Consulte com filtros

A listagem aceita paginação, ordenação, janelas de data e nove operadores de filtro sobre qualquer propriedade, inclusive aninhada.

const pagina = await api.list('produtos', {
  page: 1,
  limit: 20,
  sort: 'createdAt',
  direction: 'desc',
  filters: {
    ativo: { eq: true },
    preco: { gte: 100, lte: 500 },
    nome: { contains: 'mecanico' },
  },
});

console.log(pagina.items, pagina.pagination);
Quer todas as formas de filtrar?A referência tem cada operador com exemplo, conversão de tipos, caminhos aninhados, arrays, intervalos e os limites de cada consulta. Abrir a seção de filtros →

Passo 6

Altere e exclua

PATCH mescla (JSON Merge Patch), PUT substitui tudo e DELETE faz exclusão lógica. As três operações incrementam ou preservam version.

// Atualizacao parcial (merge)
await api.patch('produtos', produto.id, { preco: 329.9, estoque: 10 });

// Substituicao completa
await api.replace('produtos', produto.id, { nome: 'Teclado RGB', preco: 399.9 });

// Leitura e exclusao logica
const atualizado = await api.get('produtos', produto.id);
await api.delete('produtos', produto.id);

Métodos do SDK

create(namespace, data)list(namespace, options)get(namespace, id)replace(namespace, id, data)patch(namespace, id, patch)delete(namespace, id)

Passo 7

Trate os erros

Todo erro traz um code estável e um requestId. Guarde o requestId ao investigar uma falha: ele localiza a requisição nos registros técnicos.

try {
  await api.get('produtos', 'id-invalido');
} catch (error) {
  if (error instanceof JsonDockApiError) {
    console.error(error.status, error.code, error.message);
    console.error(`Request ID: ${error.requestId}`);
  }
}

A tabela completa de códigos está na referência da API.

Próximo passo

Agora que o básico funciona, a referência cobre todos os parâmetros do GET, os limites de payload, o rate limit e os códigos de erro.

Abrir a referência da APIVer os filtros