Other

SDS (Session Data Storage)

914 views August 7, 2017 September 18, 2018 3

Using SDS will help you avoid transferring large amounts of data in your web service requests and to isolate file transfers from the rest of your business logic. SDS is typically used together with other Signicat products such as the DocumentService and the PackagingService.

Files are uploaded and downloaded to and from SDS using plain HTTP, so in order to upload a document you HTTP POST it and to download you HTTP GET it. The requests are authenticated using Basic authentication, where the username is your service name and the password is the same as in your web service requests. Signicat Operations will help you acquire the correct credentials for your integration.

Uploading

In order to transfer a file to SDS, you execute an HTTP POST request which needs to contain the following information:

  1. Credentials — the requests are authenticated using Basic authentication, where the username is your service name and the password is the same as in your web service requests. Signicat Operations will help you acquire the correct credentials for your integration. In production you´ll need a client certificate as well, see How to get a client SSL web service certificate.
  2. Content-Type — must reflect the type of content you´re uploading, i.e. “application/pdf” for PDF, “text/plain” for text etc.
  3. Body — simply put the file contents in the request body.
Example HTTP request
POST https://preprod.signicat.com/doc/demo/sds HTTP/1.1
Content-Type: application/pdf
Authorization: Basic c2hhcmVkOkJvbmQwMDc=
Host: preprod.signicat.com
Content-Length: 688343
Expect: 100-continue

%PDF-1.5
%âãÏÓ
1 0 obj
<</Metadata 2 0 R/OCProperties<</D<</OFF[10 0 R 11 0 R 12 0 R]/ON[13 0 R 14 0 R 15 0 R 16 0 R 17 0 R 18 0 R 19 0 R 20 0 R 21 0 R 22 0 R 23 0 R 24 0 R 25 0 R 26 0 R 27 0 R 28 0 R 29 0 R 30 0 R]/Order 31 0 R/RBGroups[]>>/OCGs[10 0 R 13 0 R 14 0 R 15 0 R 16 0 R 17 0 R 18 0 R 11 0 R 19 0 R 20 0 R 21 0 R 22 0 R 23 0 R 12 0 R 24 0 R 25 0 R 26 0 R 27 0 R 28 0 R 29 0 R 30 0 R]>>/Pages 3 0 R/Type/Catalog>>
[a lot of PDF mumbo jumbo here] >>
startxref
683190
%%EOF
Example HTTP response
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Date: Wed, 21 Aug 2013 10:04:44 GMT
Set-Cookie: JSESSIONID=60CDAA2C7E7C5B202F58DA00715327AF.test01; Path=/doc; Secure
Location: http://localhost:8085/acme/21082013yuhu3a80c1kofj1baarn1gozk32hphh9jcy6i5h9a3qk2ca7z
Content-Type: text/plain;charset=ISO-8859-1
Content-Length: 57

21082013yuhu3a80c1kofj1baarn1gozk32hphh9jcy6i5h9a3qk2ca7z

Please note that a successful request results in a HTTP 201 Created response. Other HTTP codes you may receive are:

  • HTTP 400 Bad Request — most likely, your request is syntactically incorrect and could not be understood by the server.
  • HTTP 500 Internal Server Error — the service failed to complete your request for undisclosed reasons.

Given a successful request, then the response body will contain a string which may be up to 64 characters long. The document is guaranteed to remain on the server for 30 minutes, after which it will be deleted unless it has been used in a subsequent web service request.

Downloading

In order to transfer a file from SDS, you execute an HTTP GET request which needs to contain the following information:

  1. Credentials — the requests are authenticated using Basic authentication, where the username is your service name and the password is the same as in your web service requests. Signicat Operations will help you acquire the correct credentials for your integration. In production you´ll need a client certificate as well, see How to get a client SSL web service certificate.
  2. The URL contains the document id and will have the following format: https://environment.signicat.com/doc/servicename/sds/documentid where the fragments written in italic are subject to change.
Example HTTP request
GET https://preprod.signicat.com/doc/demo/sds/260820133373l363x69jzc74qs3vo2hittigyd0spy1wwk60rk6z70278m HTTP/1.1
Authorization: Basic ZGVtbzpCb25kMDA3
Host: preprod.signicat.com
Example HTTP response
HTTP/1.1 200 OK
Date: Mon, 26 Aug 2013 11:40:07 GMT
Content-Type: application/pdf
Content-Length: 688343

%PDF-1.5
%âãÏÓ
1 0 obj
<</Metadata 2 0 R/OCProperties<</D<</OFF[10 0 R 11 0 R 12 0 R]/ON[13 0 R 14 0 R 15 0 R 16 0 R 17 0 R 18 0 R 19 0 R 20 0 R 21 0 R 22 0 R 23 0 R 24 0 R 25 0 R 26 0 R 27 0 R 28 0 R 29 0 R 30 0 R]/Order 31 0 R/RBGroups[]>>/OCGs[10 0 R 13 0 R 14 0 R 15 0 R 16 0 R 17 0 R 18 0 R 11 0 R 19 0 R 20 0 R 21 0 R 22 0 R 23 0 R 12 0 R 24 0 R 25 0 R 26 0 R 27 0 R 28 0 R 29 0 R 30 0 R]>>/Pages 3 0 R/Type/Catalog>>
[a lot of PDF mumbo jumbo here] >>
startxref
683190
%%EOF

A successful request results in a HTTP 200 OK response. Other HTTP codes you may receive are:

  • HTTP 400 Bad Request — your request is syntactically incorrect and could not be understood by the server.
  • HTTP 404 Not Found — the document corresponding to the given document id could not be found.
  • HTTP 500 Internal Server Error — the service failed to complete your request for undisclosed reasons.

Using the command line and the pre-production environment

Obviously, using the command line to manually upload documents to SDS is not something you would normally do in a production scenario. It can however be very convenient during testing and when understanding how the service works. The following examples uses cURL to execute HTTP requests from the command line:

Uploading a text document using cURL
# Windows
curl -u demo:Bond007 -k -d "Test document with ÅÆØ" -H "Content-Type: text/plain;charset=iso8859-1" https://preprod.signicat.com/doc/demo/sds

# OS X/Linux
curl -u demo:Bond007 -k -d "Test document with ÅÆØ" -H "Content-Type: text/plain;charset=utf8" https://preprod.signicat.com/doc/demo/sds

# Explanation of parameters:
# -u service_name:password
# -k accept the server SSL certificate without validation
# -d request data (which implies HTTP POST instead of HTTP GET)
# -H set request header
In this example, we uploaded an inline string and not really a “text document”, but of course it´s possible to upload a text file as well. To upload a PDF file, you need to HTTP POST the binary file in the request body. Such a cURL request for a PDF document called mydocument.pdf would look something like this:
Uploading a PDF document using cURL
# Windows/OS X/Linux
curl -u demo:Bond007 -k --data-binary @mydocument.pdf -H "Content-Type: application/pdf" https://preprod.signicat.com/doc/demo/sds

Uploading a document returns a document id which can be used to download the document:

HTTP GET URL
https://preprod.signicat.com/doc/demo/sds/21082013yuhu3a80c1kofj1baarn1gozk32hphh9jcy6i5h9a3qk2ca7z

You can use any browser to fetch the document (username: demo, password: Bond007), or you can use cURL to issue a HTTP GET:

Downloading a document using cURL
curl -u demo:Bond007 -k -o mydownloadedfile.pdf https://preprod.signicat.com/doc/demo/sds/21082013yuhu3a80c1kofj1baarn1gozk32hphh9jcy6i5h9a3qk2ca7z

Which will GET the file and save it to mydownloadedfile.pdf.

Using the command line and the production environment

In the production environment, you will get your own web service that requires two-way ssl. This differs from the pre-production. Read more about The pre-production environment here.

For the production environment, you will receive a web service certificate in p12 format. Curl needs a certificate in pem format, so you need to convert it first. The certificate decryption password will be provided to you after you have downloaded the neccessary p12 file. Please substitute the variables below:

$openssl pkcs12 -in your-webservice-certificate.p12 -out your-webservice-certificate.pem -clcerts
Enter Import Password: <Enter decryption password>
MAC verified OK
Enter PEM pass phrase: <Enter new passphrase for the pem file here>
Verifying - Enter PEM pass phrase: <Enter pem passphrase again>

When you have your web service certificate file in pem format, you can use the command below. Please do note that you need to replace the placeholders. The servicename, certificate decryption password and web service password will be provided to you by signicat. Again, using curl against the production environment is something you normally would do only to verify your two way ssl setup before going live.

curl --tlsv1 --cert <./your-webservice-certificate.pem>:<pem passhrase> -u <yourservice>:<yourwebservicepassword> -k -d"Two-way SSL Uploaded document with ÆØÅ" -H "Content-Type: text/plain;charset=utf-8"  https://id.signicat.com/doc/<yourservice>/sds

The return value from a POST to the URL above will be a string which can be used as sds-ref-id in a documentservice call (Please take a look at the Documentservice API here). The first 8 characters of the return value will contain todays date in ddmmyyyy format.

Using Node.js

Uploading a document using Node.js
// HTTP POST PDF to Signicat SDS
// using Node.js (http://nodejs.org)
// and the request library (https://github.com/mikeal/request)

var fs = require('fs');
var request = require('request');

fs.createReadStream('mydocument.pdf').pipe(
    request.post(
        'https://preprod.signicat.com/doc/demo/sds/',
        function (error, response, body) {
            if (!error && response.statusCode == 201) {
                console.log(body);
            }
            else {
                console.log(error);
            }
        }
    ).auth(
        'demo',
        'Bond007'
    )
);
Downloading a document using Node.js
// HTTP GET PDF from Signicat SDS
// using Node.js (http://nodejs.org)
// and the request library (https://github.com/mikeal/request)
var fs = require('fs');
var request = require('request');

var url = 'https://preprod.signicat.com/doc/demo/sds/23082013f7mycvs9u35wrwg954qa9wmsn50mtwlatf3ygjy09yj8kkp3q';
request(url).auth('demo', 'Bond007').pipe(fs.createWriteStream('mydownloadedfile.pdf'));

Using Java and Apache HttpClient

Uploading a document using Java
package com.signicat.sds;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.Credentials;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.FileEntity;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.junit.Test;
import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;
public class UploadSds {
    @Test
    public void uploading_a_pdf_to_sds_using_apache_http_client() throws IOException {
        // Create the client and set it up for basic authentication
        AuthScope authScope = new AuthScope("preprod.signicat.com", 443);
        Credentials credentials = new UsernamePasswordCredentials("demo", "Bond007");
        CredentialsProvider credsProvider = new BasicCredentialsProvider();
        credsProvider.setCredentials(authScope, credentials);
        CloseableHttpClient client = HttpClients.custom()
                .setDefaultCredentialsProvider(credsProvider)
                .build();
        // Grab the PDF file and add it to the HttpPost request
        HttpPost post = new HttpPost("https://preprod.signicat.com/doc/demo/sds");
        File pdf = new File("src/test/resources/demo_avtale.pdf");
        post.setEntity(new FileEntity(pdf, ContentType.create("application/pdf")));
        // Execute the request and read the document id from the response
        HttpResponse response = client.execute(post);
        BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
        String line = rd.readLine();
        assertNotNull(line);
        assertEquals(58, line.length());
    }
}
Downloading a document using Java
package com.signicat.sds;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.Credentials;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.junit.Test;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertTrue;
public class DownloadSds {
    @Test
    public void downloading_a_pdf_to_sds_using_apache_http_client() throws IOException {
        // Create the client and set it up for basic authentication
        AuthScope authScope = new AuthScope("preprod.signicat.com", 443);
        Credentials credentials = new UsernamePasswordCredentials("demo", "Bond007");
        CredentialsProvider credsProvider = new BasicCredentialsProvider();
        credsProvider.setCredentials(authScope, credentials);
        CloseableHttpClient client = HttpClients.custom()
                .setDefaultCredentialsProvider(credsProvider)
                .build();
        // Construct the URL to the document and add it to the HttpGet request
        String documentId = "180520162syjw99j2seogz60o6kls2hqtt3obbdpbym1bw8w9po0y86iyh";
        String sdsUrl = "https://preprod.signicat.com/doc/demo/sds/" + documentId;
        HttpGet get = new HttpGet(sdsUrl);
        // Execute the request and read+save the document id from the response
        HttpResponse response = client.execute(get);
        File pdf = new File("mydownloadedfile.pdf");
        FileOutputStream out = new FileOutputStream(pdf);
        HttpEntity entity = response.getEntity();
        entity.writeTo(out);
        out.close();
        assertEquals(200, response.getStatusLine().getStatusCode());
        assertTrue(response.getFirstHeader("Content-Type").getValue().startsWith("application/pdf"));
    }
}
Downloading a document using Node.js
// HTTP GET PDF from Signicat SDS
// using Node.js (http://nodejs.org)
// and the request library (https://github.com/mikeal/request)
var fs = require('fs');
var request = require('request');

var url = 'https://preprod.signicat.com/doc/demo/sds/23082013f7mycvs9u35wrwg954qa9wmsn50mtwlatf3ygjy09yj8kkp3q';
request(url).auth('demo', 'Bond007').pipe(fs.createWriteStream('mydownloadedfile.pdf'));

Using C# and the .NET 4.5 HttpClient

Uploading a document using C#
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace Signicat.Support.SDS.Test
{
    [TestClass]
    public class SDSTest
    {
        [TestMethod]
        public async Task Uploading_a_PDF_document_to_SDS()
        {
            var httpClientHandler = new HttpClientHandler { Credentials = new NetworkCredential("demo", "Bond007") };
            using (var client = new HttpClient(httpClientHandler))
            {
                HttpContent content = new ByteArrayContent(File.ReadAllBytes("mydocument.pdf"));
                content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
                HttpResponseMessage response =
                    await client.PostAsync("https://preprod.signicat.com/doc/demo/sds", content);
                string documentId = await response.Content.ReadAsStringAsync();

                Assert.AreEqual(HttpStatusCode.Created, response.StatusCode);
                Assert.IsTrue(documentId.Length > 0);
            }
        }
    }
}
Downloading a document using C#
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace Signicat.Support.SDS.Test
{
    [TestClass]
    public class SDSTest
    {
        [TestMethod]
        public async Task Downloading_a_PDF_document_from_SDS()
        {
            var httpClientHandler = new HttpClientHandler { Credentials = new NetworkCredential("demo", "Bond007") };
            using (var client = new HttpClient(httpClientHandler))
            {
                HttpResponseMessage response =
                    await client.GetAsync("https://preprod.signicat.com/doc/demo/sds/26082013589fl9ppby4c7ltrgyp11kx41bc9mikazp2yhcsk11fgxfgxtd");
                byte[] pdf = await response.Content.ReadAsByteArrayAsync();
                File.WriteAllBytes("mydownloadedfile.pdf", pdf);

                Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
                Assert.AreEqual("application/pdf", response.Content.Headers.ContentType.ToString());
            }
        }
    }
}

Note: The example in C# uses the async syntax and HttpClient in .NET 4.5. If you don´t like that, please feel free to use the System.Net.Webclient:

Using System.Net.WebClient
using (var webClient = new WebClient())
{
    webClient.Credentials = new NetworkCredential("demo", "Bond007");
    byte[] document = webClient.DownloadData(urlToDownload);
}

Was this helpful?