Criando um repositório para informações imutáveis

A Plataforma 2Ledger simplifica e acelera a adoção da tecnologia blockchain em seus negócios. Integrar com ela é super simples basta criar uma conta e começar a utilizar a sua API.

A API foi toda desenvolvida seguindo os princípios do padrão RESTful e permite a integração com praticamente todas as linguagens de programação mais modernas.

O primeiro passo é criar a sua conta na 2Ledger. Caso ainda não tenha realizado poderá fazê-lo clicando aqui.

Autenticação

O primeiro passo para utilizar a API é obter o token que será utilizado em todas as interações com a plataforma. A autenticação da plataforma 2Ledger utiliza o padrão Basic Access Authentication. Para realizar a autenticação basta fazer a seguinte requisição:

//Credentials (login:password) in base64 format
var credentials = "bWFyY2lvQDJsZWRnZXsuY28tOkNnN2RuaHh0";

$.ajax({
   url: "https://api.2ledger.com/v1/login",
   method: "post",
   beforeSend: function(request) {
       request.setRequestHeader("Accept", "application/json");
       request.setRequestHeader("Authorization", "Basic " + credentials);
   },
   success: function( result ) {
       var token = result.response;
       console.log(token);
   },
   error: function (err) {
       console.log("Authentication failed: " + err.responseJSON, err);
   }
});

O header Authorization é o resultado da combinação login:password em formato Base64 e se passado corretamente retorna o token como resposta.

No caso da autenticação falhar um erro http 400 será retornado. Verifique novamente as credenciais informadas e tente novamente.

Autorização

Todas as operações de interação com a API da Plataforma 2Ledger implementam o padrão Bearer Token e exigem o token retornado no tópico anterior no header Authorization de cada requisição.

//Add an authorization header into request
request.setRequestHeader("Authorization", "Bear " + token);

Caso o token informado não seja válido um erro http 401 Unauthorized será retornado informando a necessidade de um token válido. Nesse caso retorne ao tópico anterior para obter um token válido.

Criação de uma rede

Todas as operações realizadas na plataforma 2Ledger dizem respeito a alguma rede criada entre seus participantes para interagirem entre si. Caso essa rede ainda não tenha sido criada ela poderá ser criada conforme requisição a seguir informando um nome para a rede e a sua descrição.

//Token created during login
var token = "my token";

$.ajax({
       url: "https://api.2ledger.com/v1/networks",
       method: "post",
       beforeSend: function(request) {
           request.setRequestHeader("Accept", "application/json");
           request.setRequestHeader("Authorization", "Bearer " + token);
       },
       data: { name: "mynetwork", description: "Network test" },
       success: function( result ) {
           console.log(result);
       },
       error: function (err) {
           console.log("Error: " + err.responseJSON, err);
       }
});

Caso a rede seja criada com sucesso a requisição irá retornar o código 200 e um objeto JSON com o metadado da rede criada. A propriedade “response._id” do objeto retornado define a identificação única da rede a ser utilizado posteriormente ao interagir com ela.

Caso a requisição para a criação da rede falhe um retorno http 400 Bad Request será retornado.

Criação de uma entidade

Um dos benefícios do blockchain é a garantia de registro de informações imutáveis e à prova de fraudes. Na plataforma 2Ledger isso é possível por meio da criação de uma entidade para armazenamento de objetos (quem podem ser uma simples string, um JSON ou um XML).

As entidades são como um repositório e são criadas dentro de uma rede da plataforma. Uma entidade pode ser compartilhada entre os participantes de uma rede mas os seus itens uma vez armazenados nunca mais podem ser alterados.

As entidades podem ser utilizadas para a criação de prova de existência de um documento digital ou para criação de catálogos distribuídos de informações por exemplo. Semelhante ao que se pode fazer com uma tabela de banco de dados.

Para criar uma entidade é necessário realizar uma requisição conforme descrito a seguir informando o identificador da rede onde a entidade será criada (obtida no momento da criação da rede), um nome para a entidade e a sua descrição:

//creating a entity
var token = "my token";
var network = '5b47e81ecd80440038702153';

$.ajax({
       url: "https://api.2ledger.com/v1/networks/"+network+"/entities",
       method: "post",
       beforeSend: function(request) {
           request.setRequestHeader("Accept", "application/json");
           request.setRequestHeader("Authorization", "Bearer " + token);
       },
       data: { name: "documents", description: "Entity to store digital documents." },
       success: function( result ) {
           console.log(result);
       },
       error: function (err) {
           console.log("Error: " + err.responseJSON, err);
       }
});

Caso a entidade seja criada com sucesso a requisição irá retornar o código 200 e um objeto JSON com o metadado da entidade criada. A propriedade “response._id” do objeto retornado define a identificação única da entidade a ser utilizado posteriormente ao interagir com ela.

Criação de um registro

Na plataforma 2Ledger os documentos imutáveis são armazenados como registros nas entidades criadas. É a partir do registro imutável de documentos que a tecnologia blockchain é utilizada para o registro de trilhas de auditoria, logs de acesso, prova de existência e autenticidade por exemplo.

Para armazenar um registro é necessário invocar o endpoint abaixo informando, além do identificador da entidade (criado no momento de seu cadastro), uma chave (key) e seu conteúdo (pode ser um XML ou JSON por exemplo).

É importante observar que por se tratar de uma tecnologia imutável um registro poderá ser cadastrado mais de uma vez com a mesma chave e normalmente um atributo de versão é incluído no seu conteúdo.  

//creating a record
var token = "my token";
var entity = '5b4718sacd824400387s2155';

$.ajax({
       url: "https://api.2ledger.com/v1//entities/"+entity+"/records",
       method: "post",
       beforeSend: function(request) {
           request.setRequestHeader("Accept", "application/json");
           request.setRequestHeader("Authorization", "Bearer " + token);
       },
       data: { key: "ID123456", value: "76sd78a9s7f9s0asd56as7d" },
       success: function( result ) {
           console.log(result);
       },
       error: function (err) {
           console.log("Error: " + err.responseJSON, err);
       }
});

Caso um registro seja criado com sucesso a requisição irá retornar o código 200 e um objeto JSON com o metadado do registro criado. A propriedade “response.txid” do objeto retornado define a identificação única da entidade a ser utilizado posteriormente ao interagir com ele.

Consultando um registro

A plataforma 2Ledger permite, dentre outras coisas, a consulta da última versão de um registro por meio de sua chave (key) conforme a seguir. Para realizar essa consulta é necessário informar a chave informada no momento do registro.

//find a record
var token = "my token";
var key = 'ID123456';

$.ajax({
       url: "https://api.2ledger.com/v1/records/"+key,
       method: "get",
       beforeSend: function(request) {
           request.setRequestHeader("Accept", "application/json");
           request.setRequestHeader("Authorization", "Bearer " + token);
       },
       success: function( result ) {
           console.log(result);
       },
       error: function (err) {
           console.log("Error: " + err.responseJSON, err);
       }
});

Caso o registro seja encontrado a requisição retornará um código http 200 e um objeto json onde a propriedade “response.record” possui as informações do documento. Caso não seja encontrado o registro um erro http 404 Not Found será retornado.

Considerações finais

O objetivo deste documento é apresentar ao usuário da plataforma 2Ledger os primeiros passos para a utilização de sua API, especificamente para o registro de documentos digitais imutáveis.

Mais informações sobre a utilização da plataforma 2Ledger e sua API podem ser encontradas na área administrativa acessível em https://admin.2ledger.com ou em https://blog.2ledger.com.

Anúncios

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair /  Alterar )

Foto do Google

Você está comentando utilizando sua conta Google. Sair /  Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair /  Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair /  Alterar )

Conectando a %s