Docstore


What does Docstore do?


Docstore accepts data ("documents") over http and stores it for later use by Condé Nast's various departments. Each document is treated as a separate entity bearing no relation to any other documents previously submitted; it is all non-relational, schema-less data.

Docstore is also tied to Condé Nast's newsletter subscription service, and, depending on what data is in a document submitted to docstore, a user may be signed up to one of Condé Nast's mailing lists or entered into their email marketing database when a document is stored.

A common use of docstore is to store information submitted by users from competitions or survey forms on our websites.

It is, however, general purpose and can be used to store any data whatsoever for almost any purpose, but survey and competition forms is the most common use-case.

How do I use docstore?


Docstore is accessed via http at http://docstore.api.condenet.co.uk/

To create a document in Docstore, data must be sent as POST data to a known database and collection endpoint, such as http://docstore.api.condenet.co.uk/db/test/test/.

A request sent to this endpoint will create a document in the test collection of the test database.

Docstore has the concept of databases and collections. Generally, a database will be Condé Nast brand specific, and the collection will be 'project' specific. For example, an valid endpoint may be http://docstore.api.condenet.co.uk/db/gq/bally-2015/, indicating GQ's database and the 'bally-2015' collection.

Docstore usage examples


The below code snippet shows a standard HTML form submitting a document to the 'gq/bally-2015' collection.

<form action="https://docstore.api.condenet.co.uk/db/gq/bally-2015/" method="post">
    <p>Your answer</p>
    <input type="text" name="competition_answer">

    <p>Your email</p>
    <input type="email" name="email">

    <p>Tick if you wish to receive offers from Condé Nast</p>
    <input type="checkbox" name="optin_Condénast">

    <p>Tick if you wish to receive offers from carefully selected third parties</p>
    <input type="checkbox" name="optin_thirdparty">

    <input type="hidden" name="_redirect" value="http://mysite.com/#success">

    <button type="submit">Submit answer!</button>
</form>

If this form was submitted, a document would be created in the gq/bally-2015 collection. It is worth noting that Docstore does no validation of data, you as the developer of the form are expected to ensure that the data submitted is 'correct' (for your own definition of correct).

Upon further inspection you will notice a few things

  • The form action is the docstore database and collection endpoint that you wish to write data into
  • The form method has to be post
  • Three of the form inputs: email, optin_condenast, optin_thirdparty are 'special' inputs. If docstore notices these three inputs together, the email and their preferences will be automatically entered into the marketing database.
  • The _redirect input and value input will prompt the response from Docstore to include a Location header, which will redirect the user to a new page upon submitting the form. If no redirect value is submitted, no redirect will be issued.

You can use Docstore via XMLHTTPRequest with jQuery (for example):

// create object to hold form data
  var form_data = {};

  // append email into object
  form_data['email'] = $('input[name=email]).val();

  // if optin_Condénast was set, append it into the form data
  if ($('input[name=optin_Condénast]').is(':checked')) {
    form_data['optin_Condénast'] = '1';
  }

  // if optin_thirdparty was set, append it into the form data
  if ($('input[name=optin_thirdparty]').is(':checked')) {
    form_data['optin_thirdparty'] = '1';
  }

  // send the request, and handle a success or fail status accordingly
  $.ajax({
    url: 'https://docstore.api.condenet.co.uk/db/gq/bally-2015/',
    type: 'POST',
    data: form_data
  }).done(function() {
    $('#form-success').show();
  }).fail(function () {
    $('#form-errors').show();
  });

In the above code, the redirect parameter is not required as the javascript code can handle showing a 'success' indicator itself.

Important things to note

  • Docstore is deliberately not RESTful, as it is primarily designed to accept form submissions from web pages
  • It is of critical importance to note that each database and collection must be created ahead of time. These values cannot just be made up. This is a change from the old form-entries/formdata service which would accept any values whatsoever.
  • You should use https:// over http://. Docstore will work over both protocols, but https is preferred due to the sensitive nature of the data usually submitted to docstore (emails and other personally identifiable data)
  • To have a database and collection created, please liaise with your Conde Nast project manager if they have not already told you which database and collection to post documents to.
  • It is preferred, and much easier, to use Docstore via XHR requests. Submitting forms directly to Docstore is only recommended as a 'fall back' when used from a browser.
  • Note that for the special optin_ values, ANY value indicates an opt-in. Ie, their presence alone indicates that a user has opted in. Sending a value of '0' or 'false' or any "falsey" value will still result in an opt-in. Beware!
  • Spam and abuse detection is built into Docstore. However, this spam detection is not transparent and will not be indicated in any responses from Docstore. That is to say, documents may be silently discarded.
  • Responses always come in the form of a 201 Created response with a JSON body indicating the UUID of the document created
  • Collections can be closed; meaning no more documents will be accepted. In this case, a 403 Forbidden response will be returned
  • You can use Docstore in your own back-end code, meaning your back-end code will submit requests to Docstore rather than your users (either via XHR or via forms). In this case, you should pass the IP and User Agent of the user your back-end code is acting on behalf of via form data parameters named _remote_addr and _user_agent.