Api Documentationv1.0

Intro

This is the DataEngrave's API usage English Documentation. This API allows you to make your own blockchain applications, as well as integrations of our recording, recovery and other services.

The API is presented as a set of RESTFUL services that can be used through HTTP protocol by any type of application capable of making HTTP calls with GET, POST, PUT and DELETE methods.

Application register

You need a registered application in order to call any API function. This application should appear at your company's dashboard. You can create it from the dashboard clicking into "New application".

Inside every application's dashboard, and for each one, you can get an ID and a KEY. These strings are required at any API call. Please, En su panel de aplicaciones y para cada una de ellas, podrá obtener un ID y una KEY. Estas cadenas son necesarias para cualquier llamada al API, please, store them properly.

API Access

Credentials

As we told before, you need the API credentails included at any API call. Being a RESTFUL system we don't keep status between calls, so there's no cookie that can keep a session authentication.

There's two required authentication headers at every request:

X-Auth-UserContaining the application's ID
X-Auth-KeyContaining the application's KEY

Previous Requisites

  • A registered application.
  • The ID and the KEY from that application.
  • The knowledge of any programing language wich can send HTTP requests and handle JSON or XML.

Calling to the API

URL

Every API call have the same base URL:

  • https://dataengrave.com/api

Parameters

In a POST method, all the params should be sent as a JSON or XML string in the request BODY, referencing the choosen format using the Content-Type header. So, the first thing to do is to code up a routine wich can send a POST request attaching a JSON/XML array inside the request body.

Response

In the same way when the response needs to include some information, this is to be send in a JSON or XML array and included inside its body.

Headers

Authentication
HeaderTypeDescription
X-Auth-UserStringApplication's ID
X-Auth-KeyStringApplication's KEY
Format
HeaderTypeValueDescription
Content-TypeString, mime-typeapplication/json, application/xmlWhen data is present, data format in the request's body.
AcceptString, mime-typeapplication/json, application/xmlRequested format to receive API reponse.

Supported languages

Any programming language wich support HTTPS calls and JSON/XML array encoding and decoding. In other words: any modern language and some of ancient ones.

API Functions

API is exposing a set of functions wich can be used to manage all the blockchain avaliable services. All functions can respond in JSON or XML format, just finish the called URL as .xml or .json, or use the Accept header instead.

In the same way you can send parámeters as XML or JSON and in this case you need to tell us the format using the Content-type header, containing application/xml or application/json.

Resource list

System/api/system
ResourceMethodFunction nameResponseDescription
/GETsystem-statusjson/xmlSystem Status
/timeGETsystem-timejson/xmlSystem Date and Time
Company/api/company
ResourceMethodFunction nameResponseDescription
/GETcompany-infojson/xmlCompany data and network addresses
/balanceGETcompany-balancejson/xmlRecover actual company balance
Operation/api/operation
ResourceMethodFunction nameResponseDescription
/POSTengravejson/xmlEngravement Operation
/GETretrieve-alljson/xmltranslation missing: en.docs.resources.operation.retrieve
/<id>GETretrieve-idjson/xmlGet one operation
/<id>DELETEbanjson/xmlBan Operation

Every resource and its parameters are described in the next chapters.

System

System Status

URL
[GET] https://dataengrave.com/api/system
Parameters

This method doesn't need any params.

Call example
curl -XGET -H 'X-Auth-User: app_id' -H 'X-Auth-Key: app_key' -H 'Accept: application/json' \
  'https://dataengrave.com/api/system'
Please put your own application id and key.
Response example
{
  ok: true,
  msg: 'All services UP',
  services: [
    { id: 'test_wallet_run', name: 'Test wallet', up: true, at: 1_517_254_302 },
    { id: 'main_wallet_run', name: 'Main wallet', up: true, at: 1_517_254_302 },
    { id: 'task_det_info_run', name: 'Task det:info', up: true, at: 1_517_254_302 },
    { id: 'task_det_balances_run', name: 'Task det:balances', up: true, at: 1_517_254_331 }
  ]
}
Numbers are represented as 1_000_000, but they are simple integers.

System Date and Time

URL
[GET] https://dataengrave.com/api/system/time
Parameters

This method doesn't need any params.

Call example
curl -XGET -H 'X-Auth-User: app_id' -H 'X-Auth-Key: app_key' -H 'Accept: application/json' \
  'https://dataengrave.com/api/system/time'
Please put your own application id and key.
Response example
{ ok: true, msg: 'My Unix Timestamp', timestamp: 1_517_310_436 }

Company

Company data and network addresses

URL
[GET] https://dataengrave.com/api/company
Parameters

This method doesn't need any params.

Call example
curl -XGET -H 'X-Auth-User: app_id' -H 'X-Auth-Key: app_key' -H 'Accept: application/json' \
  'https://dataengrave.com/api/company'
Please put your own application id and key.
Response example
{
  ok: true,
  msg: 'Company data',
  company: {
    id: 'your_company_id',
    nick: 'your_company_nick',
    name: 'Your Company Name',
    addresses: {
      test: 'testnet_wallet_address',
      main: 'mainnet_wallet_address'
    },
    enabled: true
  }
}

Recover actual company balance

URL
[GET] https://dataengrave.com/api/company/balance
Parameters

This method doesn't need any params.

Call example
curl -XGET -H 'X-Auth-User: app_id' -H 'X-Auth-Key: app_key' -H 'Accept: application/json' \
  'https://dataengrave.com/api/company/balance'
Please put your own application id and key.
Response example
{
  ok: true,
  msg: 'Your company balance',
  main: {
    balance: 1.0,
    confirmed: 1.0,
    unconfirmed: 0.0
  },
  test: {
    balance: 1.7450781,
    confirmed: 1.7450781,
    unconfirmed: 0.0
  }
}

Operation

Get one operation

URL
[GET] https://dataengrave.com/api/operation/<operation_id>
Parameters

Replace operation_id, at the URL, by the operation ID to retrieve.

Call example
curl -XGET -H 'X-Auth-User: app_id' -H 'X-Auth-Key: app_key' -H 'Accept: application/json' \
  'https://dataengrave.com/api/operation/<operation_id>'
Please put your own application id and key.
Response example
{
  ok: true,
  msg: 'Your operation',
  count: 1,
  operation: {
    id: 'hex_string_operation_id',
    txid: 'hex_string_transaction_id',
    net: :test,
    kind: :file,
    description: 'Operation description.',
    urls: {
      tx: 'http://localhost:9292/tx/short_url',
      file: 'http://localhost:9292/dl/short_url'
    }
  }
}

Get all operations

URL
[GET] https://dataengrave.com/api/operation
[GET] https://dataengrave.com/api/operation/page/<page>/<items_per_page>
Parameters

You can call this function with no parameters to receive a list with all the operations or you can include pagination parameters. For example to retrieve the third page with ten items for page, the URL is:

[GET] https://dataengrave.com/api/operation/page/3/10

Call example
curl -XGET -H 'X-Auth-User: app_id' -H 'X-Auth-Key: app_key' -H 'Accept: application/json' \
  'https://dataengrave.com/api/operation'
Please put your own application id and key.
Response example
{
  ok: true,
  msg: 'All operations',
  count: 16,
  operations: [
    {
      id: 'hex_string_operation_id',
      txid: 'hex_string_transaction_id',
      net: :test,
      kind: :text,
      description: 'Just a test engravement',
      urls: {
        tx: 'http://localhost:9292/tx/url'
      }
    },
    {
      id: 'hex_string_operation_id',
      txid: 'hex_string_transaction_id',
      net: :test,
      kind: :text, description: 'Another engravement test',
      urls: {
        tx: 'http://localhost:9292/tx/url' }
      },
        # ...(14 more operations)...
      {
  ]
}

Engravement Operation

URL
[POST] https://dataengrave.com/api/operation
Parameters

Params will go inside the POST request body, encoded in JSON or XML format, indicating it in the Content-Type header.

The param set changes itself depending on the recording type or kind, being one of hash, text or file:

ParamTypeRequiredContent
kindString
REQUIRED
hash, text o file
descriptionString
REQUIRED
Text UTF-8 with your description about this operation
ttpString
OPTIONAL
Time stamp authority, from the availables:
  • none: None (default), just the blockchain own time mark.
  • dataengrave: Time mark from the DataEngrave TSA.
  • eadt: Advanced Time Stamp from European Agency of Digital Trust trusted third party.
  • coloriuris: Qualifyed time stamp from Coloriuris trusted third party.
You can't ask for a timestamp seal for a custom algorithm hash.
algorithmString
If kind is hash
Used algorithm to generate this digest:
  • sha1
  • sha256
  • sha512
  • custom: You can't ask for the time stamp in this case.
digestHex String
If kind is hash
Hash to store into the blockchain
textString
If kind is text
UTF-8 text to store into the blockchain
fileArray / Tuple
If kind is file
Array or tuple (key: value) with the file data and metas
KeyTypeValue
nameStringFile name including extension
mimeStringMime type, for example: application/pdf
dataStringFile data base64 encoded
Call example
curl -XPOST -H 'X-Auth-User: <app_id>' -H 'X-Auth-Key: <app_key>' \
  -H "Content-type: application/json" \
  -d '{"kind":"hash","description":"API Test, hash SHA256, no external timestamp","algorithm":"sha256","digest":"<a_valid_sha256_digest>"}' \
  'https://dataengrave.com/api/operation'
Please put your own application id and key.
Please put your hash instead of <a_valid_sha256_digest>.
Response example
{
  ok: true,
  msg: 'Operation engraved successfully',
  operation: {
    id: '<hex_string_id>',
    txid: '<hex_string_transaction_id>',
    net: :test,
    kind: :hash,
    description: 'API Test, hash SHA256, no external timestamp',
    urls: {
      tx: 'http://localhost:9292/tx/<short_url>'
    }
  }
}

Ban Operation

A banned operation is hidden from any listing and makes itself impossible to recover using this API or through the web interface, but you should keep in mind that the operation will remain inside the blockchain from where its impossible to remove because the blockchain technology prevents any modification or deletion.

Its not possible to unban the operation, please ensure if you want to ban it.

URL
[DELETE] https://dataengrave.com/api/operation/<operation_id>
Parameters

Just the operation ID is needed, and it goes at the URL. This call is made using the DELETE method.

Call example
curl -XDELETE -H 'X-Auth-User: <app_id>' -H 'X-Auth-Key: <app_key>' \
  -H "Aceept: application/json" \
  'https://dataengrave.com/api/operation/<operation_id>'
Response example
{
  ok: true,
  msg: 'Operation banned forever'
}

Tech Support

Please, for any questions about this documentation, write us through the contact form.

We are using cookies in order to give you a better navigation experience and for our own statistics. We don't share any information with third party services or databases. You can activate the do not track mechanish in your browser if you don't want to be counted or tracked.