Dica rápida: POST para JSON:API

If you arrived here and do not speak/read/write in native Portuguese/Brazilian Portuguese or do not prefer to read in this language, this same article is written in English here.

Esta é uma dica rápida para iniciantes em JSON: APIs. Se você acha que é apenas JSON, pense novamente. É JSON e "mais algumas" definições. Aqui estão algumas coisas que eu não sabia, subestimando as especificações, e quebrei minha cabeça.

Primeiro, o Content-Type não é application/json. O tipo correto é application/vnd.api+json. Caso contrário, o servidor responderá com 415 Unsupported Media Type.

Segundo, seu payload *para fazer um POST deve * conter data (conhecido como "dados primários") e ** deve ** ter pelo menos o seguinte formato:

{
  "data": {
    "type": "meu 'segredo' estava aqui",
    "attributes": <payload>
  }
}

Se você esquecer de colocar data, receberá o seguinte erro:

{
   "errors":[
      {
         "detail":"Received document does not contain primary data",
         "source":{
            "pointer":"/data"
         },
         "status":"400"
      }
   ]
}

Você só precisa adicionar data e colocar seu payload ematributos. Depois disso, se você esquecer o type ou defini-lo como None, porque estamos fazendo um POST, você receberá o seguinte erro (ou algo semelhante):

{
   "errors":[
      {
         "detail":"The resource object's type (None) is not the type that constitute the collection represented by the endpoint (<O_NOME_DO_ENDPOINT>).",
         "source":{
            "pointer":"/data"
         },
         "status":"409"
      }
   ]
}

E o erro acima foi o que tomou minha energia e me fez escrever esse post. Demorei um pouco para descobrir, apesar da mensagem, qual foi o erro, mas pode ser diferente em outra situação/framework/estrutura, eu acho. Eis aqui a minha situação, usando Django + DRF + JSON:API:

from rest_framework.decorators import api_view

@api_view(["POST"])
def my_api_post_endoint(request):
    ...

A partir do endpoint acima, usando @api_view (e estou sendo bastante específico, porque não testei com ViewSets ou outros endpoints baseados em classe), apenas tive que definir o type do payload como o mesmo nome do endpoint. Como abaixo:

{
   "data":{
      "type":"my_api_post_endoint",
      "attributes":"payload"
   }
}

E foi isso! O POST estava passando e eu pude seguir em frente com o meu trabalho.

Moral da história? Leia a p**** das especificações antes. 😅