Project

General

Profile

ECL XML API

Search

URL: .../E/xml_search?[par1=value2[&par2=value2...]]
Method: GET

Query parameters:

  • c=<category>
  • a=<after>
    <n>days
    <n>hours
    <n>minutes
    yyyy-mm-dd[Thh:mm:ss][Z] - Z means UTC time zone, otherwise local ECL server time zone.
  • b=<before>
    <n>days
    <n>hours
    <n>minutes
    yyyy-mm-dd[Thh:mm:ss][Z] - Z means UTC time zone, otherwise local ECL server time zone.
  • f=<form name>
  • t=<tag>
  • u=<username> - author - not implemented yet
  • l=<limit>
  • st=<substring> - search for entries having specified text as substring - can be slow
  • si=<words> - indexed search for entries having the words
  • o=(ids|all) - return only entry ids or contents too. Default - all

Examples:
http://dbweb4.fnal.gov:8080/ECL/demo/E/xml_search?c=sandbox&l=10&a=90days
http://dbweb4.fnal.gov:8080/ECL/demo/E/xml_search?a=2012-04-01+12:00:00

Get

URL: .../E/xml_get?e=entry_id
Method: GET

Example: http://dbweb4.fnal.gov:8080/ECL/demo/E/xml_get?e=5

The entry is returned in XML format:

    <entry author="name" category="category" timestamp="date time" 
                        [related="entry id"]>          // related is not implemented yet
        <tag name="tag1"/>
        ...
        <attachment type="image|file" filename="filename">
            <!-- base64-encoded image or file content -->
        </attachment>
        ...
        <form name="formname">
            <field name="text">entry text</field>
            <field name="p1">field value1</field>
            <field name="p2">field value2</field>
            ...
        </form>
        <comment author="author" timestamp="date time">comment body</comment>
        ...
    </entry>

Post

URL: .../E/xml_post
Method: POST

Request body is used to pass the entry in XML format:

    <entry category="category" [private="yes"] [formatted="yes"]
                       [related="entry id"]>      //related is not implemented yet
        <tag name="tag1"/>
        ...
        <attachment type="image|file" filename="filename">
            <!-- base64-encoded image or file content -->
        </attachment>
        ...
        <form name="formname">
            <field name="text">entry text</field>
            <field name="p1">field value1</field>
            <field name="p2">field value2</field>
            ...
        </form>
    </entry>

When an entry is posted, the author is set to the authenticated client.

HTTP Request Authentication

All requests to ECL REST API are authenticated. There are 2 methods of authentication. Signature method is used by so called XML users. XML user has their unencrypted password stored in the ECL internal database and it is used as a shared secret to calculate digital signature of the request. The other method can be used to authenticate regular user. This method sends the user's password over secured HTTPS connection along with the request.

Signature Method

For the request authentication, the API uses digital signature calculated over the combination of:

  • Message body (if any)
  • URL arguments - what follows '?' in get and search methods
  • User password - not transmitted over the network, but known both by the server and the client
  • Random "salt" string

Currently, ECL client uses MD5 signature algorithm.

Signature is calculated in the following way:

1. Random "salt" string is generated. It can be any sufficiently random string, not repeating between consecutive requests. It is good idea to use current time as a seed for your random number generator, or generate random UUID.
2. Salt is added as an extra URL argument. For example, if you are searching for last 10 entries in category "A0", then your URL would look like:

http://.../E/xml_search?c=A0&l=10&salt=gbw5qeruiy34rmncqe

For post request, "salt" will be the only URL argument:

http://.../E/xml_post?salt=gbw5qeruiy34rmncqe

3. Request arguments, user password and message body (possibly empty), exactly in this order, are concatenated with colon ':' separating each part. Examples of the concatenated strings are:

c=A0&l=10&salt=gbw5qeruiy34rmncqe:myLongPassword_12345:

Notice the trailing colon for get and search requests, when the request has empty body.

salt=gbw5qeruiy34rmncqe:myLongPassword_12345:<entry author="name" category="category">
  <tag name="tag1"/>
        ...
  </entry>

Post request has the entry body which is concatenated with any leading and trailing white space stripped off.

4. The digital signature is calculated over the concatenated string.

5. The following headers are added to the HTTP request:

  X-Signature-Method: <method>       -- server accepts md5, sha1, sha512 methods
  X-User:  <username>                   -- the user to be authenticated
  X-Signature: <signature>      -- base64 encoded digital signature calculated in step 4

6. The request is sent to the server.

Password Authentication

With this method, the user name and unencrypted password are sent over HTTPS connection along with the request in 2 HTTP headers:

X-User: <username>
X-Password: <password>

This method always fails if the connection is not secure.

Get list of categories

URL: .../A/xml_category_list
Method: GET
XML output:

  <category_list>
    <category path="top"/>
    <category path="top/subtopic"/>
    ...
  </category_list>

Get list of tags

URL: .../A/xml_tag_list
Method: GET
XML output:

  <tag_list>
    <tag name="test results"/>
    <tag name="green"/>
    ...
  </tag_list>

Get list of forms

URL: .../A/xml_form_list
Method: GET
XML output:

  <form_list>
    <form name="Begin run" html="false">
      <field name="Radio" index="0" data_type="r">
        <long_name>Color</long_name>
        <parameters>red,green</parameters>
      </field>
      <field name="text" index="1" data_type="t">
        <long_name/>
      </field>
      ...
    </form>
    ...
  </form_list>