Temas

Um tema é uma folha de estilo CSS personalizada armazenada sob um código curto, e qualquer pessoa com o código pode buscá-la. A API HTTP expõe uma operação, que armazena um tema. O Media Proxy serve a folha de estilo armazenada de volta através de Obter CSS do tema.

A rota é apenas para usuários. Um token de bot e uma credencial bearer OAuth2 são ambos rejeitados com 403 ACCESS_DENIED.

Identificador de tema

Um identificador de tema possui 16 caracteres hexadecimais minúsculos que correspondem a ^[a-f0-9]{16}$. Enviar um CSS idêntico duas vezes cria dois temas independentes.

Exemplo

{
  "id": "3f0a91c7d2b84e65"
}

Limites de documento

A codificação UTF-8 de um documento enviado não pode exceder 8388608 bytes, e o documento tem pelo menos um caractere de comprimento. Ambos os limites são constantes fixas da instância.

Limite	Valor
CSS codificado1 2	8388608 bytes
CSS enviado3	pelo menos 1 caractere

¹ O limite de 8 MiB é inclusivo, então um documento cuja codificação UTF-8 é de exatamente 8388608 bytes é armazenado e um byte a mais é rejeitado com 400 FILE_SIZE_TOO_LARGE

² Medido sobre a codificação UTF-8, portanto um documento de caracteres multi-byte pode ser mais curto que 8388608 caracteres e ainda assim ser rejeitado

³ Medido em caracteres da string enviada

Uma conta não possui cota de tema. O bucket de limite de taxa theme:share:create é o único limite sobre quantos temas uma conta cria, e nenhuma rota aqui verifica uma chave de limite de instância.

Triagem de conteúdo

O filtro de conteúdo de toda a instância examina o documento enviado antes da rota ser executada. Ele verifica um valor css de pelo menos 3 caracteres contra a lista de bloqueio de frases da instância e a lista de bloqueio de URLs da instância. Uma correspondência em qualquer uma delas retorna 403 CONTENT_BLOCKED. Um valor mais curto nunca é examinado.

O Decoding Chat verifica um corpo sob qualquer tipo de conteúdo, exceto multipart/form-data e application/x-www-form-urlencoded. O filtro também ignora um corpo que não é analisado como JSON. A rota analisa o corpo a partir do texto da requisição original e não lê nenhum tipo de conteúdo, de modo que um documento JSON enviado sob qualquer formato de corpo da requisição é armazenado sem passar pelas listas de bloqueio.

A triagem precede o bucket de limite de taxa, a verificação de credencial e o esquema da requisição, portanto, um documento bloqueado retorna CONTENT_BLOCKED mesmo quando a requisição não possui credencial.

Nada mais inspeciona o documento. O Decoding Chat armazena o CSS exatamente como foi enviado e nunca o analisa, valida, minimiza ou reescreve.

Criar tema

POST/v1/users/@me/themes

Armazena um documento CSS personalizado e retorna 201 com o identificador de tema criado. Apenas para usuários, e nenhuma permissão é necessária.

Corpo JSON

Campo	Tipo	Descrição
css1 2	string	O texto CSS para armazenar e compartilhar (pelo menos 1 caractere)

¹ Armazenado exatamente como foi enviado, limitado pelo teto UTF-8 de 8388608 bytes descrito em Limites de documento

² Uma string vazia é rejeitada com o código de validação INVALID_FORMAT

Corpos malformados e inutilizáveis falham em caminhos diferentes

Um corpo ausente, um corpo apenas com espaços em branco e um css presente, mas vazio, nulo ou não-string retornam 400 INVALID_FORM_BODY com INVALID_FORMAT no caminho css. Um corpo que não é analisado como JSON retorna o mesmo status e código no caminho body.

Um corpo que é analisado como JSON mas não é um objeto, como uma string, um número, um array ou null, retorna o mesmo código no caminho root.

Corpo da resposta

Campo	Tipo	Descrição
id	string	O identificador de tema

O objeto possui o identificador e nada mais.

Resposta

Status	Corpo	Condição
201	corpo da resposta	O documento foi armazenado
400	resposta de erro	O documento codificado excede o tamanho limite e a requisição retorna FILE_SIZE_TOO_LARGE
403	resposta de erro	O chamador é um bot ou apresenta uma credencial bearer e a requisição retorna ACCESS_DENIED
403	resposta de erro	A conta tem uma ação pendente necessária e a requisição retorna ACCOUNT_SUSPICIOUS_ACTIVITY
403	resposta de erro	O documento é bloqueado pela moderação de conteúdo e a requisição retorna CONTENT_BLOCKED

Efeitos colaterais

O Decoding Chat armazena a codificação UTF-8 do documento enviado com o tipo de conteúdo text/css; charset=utf-8. O Decoding Chat termina de armazenar o documento antes de retornar o identificador.

O Media Proxy serve o documento a partir de /themes/{id}.css.

O CSS do tema é público e permanente

O identificador é a única coisa que protege um documento armazenado, e a rota de leitura não é autenticada. A API HTTP não substitui ou exclui nenhum tema armazenado. Um chamador NÃO DEVE colocar uma credencial, um token ou qualquer outro segredo em um documento enviado.

Limite de taxa

20 requisições por minuto para cada usuário autenticado, no bucket theme:share:create.