Stadsnätsportalen: Atlas API

Atlas API

Updating the MdB via API is a simple way to automate this otherwise laborious task. Please work with people experienced in communicating with API's online. Each API session needs to be authenticated using

AXA: Atlas XML API, and all data sent with this API must be encoded as UTF8.

Please mind that all API requests are sent to one web server, meaning that if you have child sites, you need to use the URL for each child site. A communication operator with four sites will this need to run this API on four different URL's

Here is some example PHP code for using insert_posts():

$api_user = 1234;
$api_key = "xxx";
$api_hash = "";
$api_url = "http://demo.stadsnatswebben.local/admin/edit/mdb_buildings/plain/api";
 
class restapi
{
    public $status;
    private $url;
    private $curl;
    function __construct($url){
        $this->url = $url;
        $this->curl = curl_init($this->url);
        curl_setopt($this->curl, CURLOPT_POST, true);
        curl_setopt($this->curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($this->curl, CURLOPT_COOKIE, "XDEBUG_SESSION=yes");
    }
    function exec($data, $method = "get"){
        if ($method == "get"){
            $url = parse_url($this->url);
            $url = $url["scheme"] . "://" . $url["host"] . $url["path"] . "?" . http_build_query($data);
            curl_setopt($this->curl, CURLOPT_URL, $url);
            curl_setopt($this->curl, CURLOPT_POST, false);
        } else {
            curl_setopt($this->curl, CURLOPT_URL, $this->url);
            curl_setopt($this->curl, CURLOPT_POST, true);
            curl_setopt($this->curl, CURLOPT_POSTFIELDS, http_build_query($data));
        }
        $response = curl_exec($this->curl);
        $xml = simplexml_load_string($response, null, LIBXML_NOCDATA | LIBXML_NOBLANKS);
        $response = json_decode(json_encode($xml), true);
        $this->status = $response[$data["method"]]["status"];
        return $response[$data["method"]]["response"] ?? false;
    }
}
 
 
$client = new restapi($api_url);
 
if ($login = $client->exec(["method" => "api_login", "api_user" => $api_user, "api_key" => $api_key])){
    print $login["message"] . "\n";
    $api_hash = $login["hash_key"];
    print "HASH: " . $login["hash_key"] . "\n";
    if ($client->status == "success"){
        $file = $argv[1] ?: "addresses.csv";
        if (($handle = fopen($file, "r")) !== false){
            $nr = 0;
            while (($data = fgetcsv($handle, 1000, ";")) !== false){
                $nr++;
                if ($nr == 1){
                    $keys = $data;
                } else {
                    $data = array_combine($keys, $data);
                    $inserts["line$nr"] = $data;
                    if ($nr % 100 == 0){
                        $status = insert_posts($inserts);
                        unset($inserts);
                        print "$nr: $status\n";
                    }
                }
            }
            if ($inserts){
                $status = insert_posts($inserts);
                print "$nr: $status\n";
            }
        }
    }
} else {
    print "Could not login\n";
}
 
 
function insert_posts($inserts){
    global $client, $api_hash;
    $post = [
        "method" => "insert_posts",
        "hash"   => $api_hash,
        "posts"  => $inserts
    ];
    $inserted = $client->exec($post, "post");
    if (!is_array($inserted)){
        $return = "PARSER ERROR";
    } else {
        $return = $client->status . CSPACE . $inserted["message"];
        foreach ($inserted["log"] as $nr => $message){
            if ($message != "Inserted successfully"){
                $return .= "\n  $nr - $message\n";
            }
        }
 
    }
    return $return;
}

Timing

It is our explicit recommendation that you run your import script during the timeframe between midnight to 7 am in the morning. The reson for this is that we run an aggregation script for XSP export at 7 am, and if you have run your import, the daily data will include that for the service providers in the following day.

Another reason is that if you were to run this during daytime, and you empty the database and insert every row, then you'd have a empty or incomplete database during a time where end customer could be searching for their address. Also, during nighttime the resource pressure on the server is much lower.

API Endpoint: Import

Import till Marknadsdatabasen 2

Endpoint URL https://www.example.com/admin/edit/mdb_buildings/plain/api

Note that this API requires authenticated user id and IP address and a hashed api credential

Method: empty_database
Will empty the database connected to the site you execute the command on.
Request Parameters

1 hash string abcd Your login hash from api_login()

Endpoint example:
GET: https://www.example.com/admin/edit/mdb_buildings/plain/api?method=empty_database&hash=abcd

success response

   <empty_database>
      <response>
         <message>Deleted all posts from MDb2 where citynet is 'ABC'</message>
      </response>
      <status>success</status>
   </empty_database>

Method: insert_post
ARRAY should be an array with PHP notation, as such: data=MNCMSN&data=Hallstahammar...

The array sent must follow the MdB2 specification
All values is validated and an error will be returned if it doesn't validate and the post isn't accepted.
All data is inserted into the DB as a new post or updates an already existing post depending on the data.

Note that this method should NOT be used to update your entire database. It can be used for pushing up small changes to the database or to test the API, but never to update your entire database, it is a far too costly method to use, when uploading large amounts of data, always use insert_posts
Request Parameters

1 hash string abcd Your login hash from api_login()

2 data array ARRAY An array of fields to be inserted to the database

Endpoint example:
GET: https://www.example.com/admin/edit/mdb_buildings/plain/api?method=insert_post&hash=abcd&data=ARRAY

success response

   <insert_post>
      <response>
         <message>Inserted 1 post successfully</message>
      </response>
      <status>success</status>
   </insert_post>

Method: insert_posts
ARRAY should be an array of arrays with PHP notation, as such: posts =MNCMSN&posts =Hallstahammar&posts =... where "post1" is the index of the post in the array.

The array accepted can only contain a maximum of 100 arrays (posts) for each request. If you have 1000 posts to insert, you need to run this function 10 times. The API will return how many posts that validated and was thus entered to the database.

Using "post###" (no spaces!) as the key for each array (post) in the request helps you understand possible error messages easier, if you have an internal ID for the data, it might be wise to use that (i.e. posts =MNCMSN)

Each post is then handled the same way as via the insert_post() method, see further information in that method
Request Parameters

1 hash string abcd Your login hash from api_login()

2 posts array ARRAY An array of posts to be inserted to the database, each post in the array the same as a single to insert_post()

Endpoint example:
GET: https://www.example.com/admin/edit/mdb_buildings/plain/api?method=insert_posts&hash=abcd&posts=ARRAY

failed response

   <insert_posts>
      <response>
         <message>2 errors</message>
         <log>
            <line2>
               <building>building can not be NULL</building>
            </line2>
            <line3>
               <building>building can not be NULL</building>
            </line3>
         </log>
      </response>
      <status>failed</status>
   </insert_posts>

success response

   <insert_posts>
      <response>
         <message>100 successes, 0 errors, 100 processed</message>
      </response>
      <status>success</status>
   </insert_posts>

1	hash	string		abcd	Your login hash from api_login()
2	data	array		ARRAY	An array of fields to be inserted to the database