Publicar via API

[marcioyonamine]

Olá,

alguém pode me passar um exemplo de como posto um item novo via API do Tainacan? Na documentação da API to achando um pouco confuso.

abs

[mateus.m.luna]

Oi @marcioyonamine vamos tentar elaborar um exemplo aqui pra vc. Mas só pra entender, vc tá querendo fazer pela API interna (via um plugin em PHP, por exemplo) ou pela API REST (via requisições ajax, por exemplo)?

[marcioyonamine]

OI Mateus, estou migrando um sistema de acervos escrito em VB/Oracle para que o Tainacan seja a interface de acesso pública. O pessoal não quer abandonar o sistema deles, mas esse sistema não tem uma interface web. Então, estou preparando um modo que atualiza o Tainacan de acordo com a atualização dessa aplicação VB. Tô fazendo em PHP fora do Taincan por enquanto para tentar entender como vai ser a dinâmica da API. A ideia é fazer um plugin que puxe desse sistema em VB.

[mateus.m.luna]

Então cara, vou ficar devendo o código por agora, mas só pra adiantar, criar um item envolveria em geral três etapas:
1 - Criar a entidade item, que tem por exemplo, o status e algumas informações mais comuns do post type do wordpress (se estão habilitados comentários, por exemplo);
2 - Criar os metadados do item (que é um repositório separado, o itemMetadata);
3 - Criar o documento/anexos do item, que são outro repositório, neste caso o de mídias do WordPress, que depois é associado via ID para os anexos do item;

Creio que um início de leitura pra essas operações pode ser este link aqui:

Tainacan Wiki

Mas temos uma demanda bem forte de melhorar a documentação de devs da Wiki. Estamos estudando uma solução de extrair documentação a partir dos comentários PHP que deve ajudar, mas tá devagar ainda…

[marcioyonamine]

Oi Mateus, uma dúvida mais específica então: quando tento enviar uma requisição em “wp-json/tainacan/v2/items/” via post, autenticando com basic-auth, enviando apenas title, description e collection_id (que parece ser o mínimo de argumentos) o que me volta é: “Nenhuma rota foi encontrada que corresponde com o URL e o método de requisição”. Eu vi tb que tem “wp-json/tainacan/v2/collection/:collection_id/items/submission”. Tentei a mesma coisa mas aí a resposta foi : “Sem permissão para fazer isso”. Alguma dica?

[vnmedeiros]

olá @marcioyonamine, muito bom saber que você vai começar a trabalhar com algo assim.
Estamos começando um projeto que vamos ter que fazer esse tipo de integração também, como o @mateus.m.luna comentou a nossa documentação ainda tá longe de ser boa
vamos gastar um esforço para melhorar as coisas ali.

Sobre a API do Tainacan estou com ideias de melhorar alguns pontos dela, por exemplo: ser mais simples para incluir novos itens, mas vamos lá:

A primeira coisa que era um pouco chato era a autenticação da API, isso melhorou bastante depois do wordpress 5.6, por conta disso aqui: Application Passwords: Integration Guide – Make WordPress Core (recomendo fortemente ler). Com esse tipo de autenticação fica melhor agora interagir com a API do Tainacan, para se criar um item praticamente é preciso fazer três coisas:

1 - criar um item “auto-draft”
2 - atualizar os valores dos metadados para esse item ainda como “auto-draft”
3 - alterar o status do item de “auto-draft” para “publico” ou “privado”

Criar o item inicialmente como “auto-draft” é necessário para que a validação dos metadados não seja disparada, por exemplo se existir um metadados que seja de preenchimento obrigatório, ao tentar publicar o item o Tainacan vai retornar um erro, já enquanto o item é um “auto-draft” isso não acontece o que facilita a sua “montagem”.

Fiz esse exemplo bem simples do uso da API (e não muito sofisticado rsrsrs), espero que seja de alguma utilidade:
basicamente esse é o funcionamento, @marcioyonamine sugiro fazer um teste simples e aos poucos vamos ajudando por aqui e claro melhorando a nossa documentação para outras pessoas!.

Att!

php_api_tainacan.php.zip (1,4,KB)

<?php
// author: Vinicius Nunes Medeiros

//https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/
// curl exemple:
// curl --insecure 'https://localhost/wp-json/tainacan/v2/collection/6/items/' -X POST -H 'Content-Type: application/json' -H 'Authorization: Basic dGFpbmFjYW46cXVQWSAwUVNFIHZFaHQgTDdMUyBXSGR2IGtyZWM=' --data-raw '{"collection_id":"6","status":"auto-draft"}'


//definição do cabeçalho das requisições utilizando o application passwords WP.
$user = 'tainacan';
$token = 'quPY 0QSE vEht L7LS WHdv krec';
$headers = array(
    'Content-Type:application/json',
    'Authorization: Basic '. base64_encode("$user:$token")
);

$collection_id = 6; // ID da coleção para criação do item


//
// ----------- Criando um Item auto-draft para receber os valores dos metadados:
//
$item_api_path = "https://localhost/wp-json/tainacan/v2/collection/$collection_id/items";
$body = array(
    "collection_id" => $collection_id,
    "status" => "auto-draft"
);

$request_params = array(
    CURLOPT_SSL_VERIFYHOST => false,
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers, 
    CURLOPT_URL => $item_api_path,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_POST => true,
);
$ch = curl_init();
curl_setopt_array($ch, $request_params);
$response_data = curl_exec($ch);
if(curl_errno($ch)){
    // throw the an Exception.
    throw new Exception(curl_error($ch));
}
curl_close ($ch);
$item = json_decode($response_data);
echo "\n \n ITEM auto-draft ID:" . $item->id . "\n\n";



//
// ----------- Adicionando/atualizando os valores dos metadados de um item
//

// --- array com o ID do metadado e o valor que o metadado vai ter para o item:
$metadatas = array(
    9 => "Valor do titulo", // Title
    11 => "Descrição", // Description
    28 => 12 // Numeric
);

foreach($metadatas as $id => $value) {
    $item_metadata_api_path = "https://localhost/wp-json/tainacan/v2/item/$item->id/metadata/$id"; // API para atualizar o valor de um metadado especifico em um item especifico.
    echo "\nitem_metadata_api_path: $item_metadata_api_path\n";
    $body = array(
        "values" => [$value]
    );
    $request_params = array(
        CURLOPT_SSL_VERIFYHOST => false,
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers, 
        CURLOPT_URL => $item_metadata_api_path,
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_CUSTOMREQUEST => 'PATCH'
    );
    $ch = curl_init();
    curl_setopt_array($ch, $request_params);
    $response_metadata = curl_exec($ch);
    if(curl_errno($ch)){
        throw new Exception(curl_error($ch));
    }
    curl_close ($ch);
    echo "\n Metadata do item $item->id atualizado: " . $response_metadata . "\n";
}


//
// ----------- Atualizando o status do item criado anteriormente como auto-rascunho
// ----------- isso é feito somente apos atulizar os metadados para que as validações dos valores dos metadados sejam executadas.
//
$item_api_path = "https://localhost/wp-json/tainacan/v2/items/$item->id";
$body = array(
    "status" => "publish"
);
$request_params = array(
    CURLOPT_SSL_VERIFYHOST => false,
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers, 
    CURLOPT_URL => $item_api_path,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_CUSTOMREQUEST => 'PATCH'
);
$ch = curl_init();
curl_setopt_array($ch, $request_params);
$response_data = curl_exec($ch);
if(curl_errno($ch)){
    throw new Exception(curl_error($ch));
}
curl_close ($ch);
$item = json_decode($response_data);

echo "\n \n ITEM publicado com ID:" . $item->id . "\n\n";

[marcioyonamine]

Show de bola! Vou tentar aqui! Esse lance do autodraft seria legal ter na documentação, pelo menos como dica.
abs

[marcioyonamine]

@vnmedeiros , funcionou perfeitamente aqui! Agradeço imensamente. Facilitou muito a minha vida!

abs