Documentation

Introduction

Welcome to the MOO API. This page will help you create applications that utilise our API. We've tried to make things as simple as possible so people with little or no programming experience can use it.

It's a simple 4 stage process:

1. Create an XML document that defines what images you want a user to be able to select from or use directly. This is broken down into a few major components:
   • The Chooser - If you just want to supply a load of images that the user can pick from to make cards
   • Filling the 'builder' - You can supply a list of images that the user must use to make cards
   • Cropping images - Specify how the images are cut into card shapes
   • Adding text - You can also specify text that can be used on cards
2. Validate that XML against our validator (it'll tell you if there's anything that looks wrong with it)
3. Wrap the XML document in a POST form
4. Err, That's it...

So, let's have a look at the 4 stages in a little more depth

Stage 1: Creating the XML document

An XML document is specifies the pack you'd like to create. The level of detail that you add to the document determines where you the user is placed in the process. For example, if you define a list of images that you want the user to select from to make a pack of cards, then they will be forwarded to the 'chooser' page. If you specify a list of images that you want them to actually use, and the 'crop' data associated with them then the user will be sent to the part of the process where they design the back of the cards. Now, we can do this the hard way or the easy way. I prefer easy, so let's look at an example of a simple request:

Images for the chooser

The above example shows how to populate the list of images that a user can choose from to make a Minicard pack with. Let's have a look at the elements that we have there. First, there's the request header:

• version - The version of XML document that you're using. We're currently on version 0.7. Mandatory.
• api_key - The API key that you have been assigned. Mandatory.
• call - The type of call that this is. This is a 'build' call and is currently they only supported call type. Mandatory
• return_to - You can specify your own page for the user to return to after they have paid for their products. The order reference will be appended to the URL as part of the query string as order_reference_id=n. Optional.
• fail_to - Like return_to this is an optional field, but it will be ignored if you are using the direct method of API request.

Next we have the payload of the actual request. As you can see, this is a chooser operation. This will place the images specified below into a window that the user can drag from to select which images they would like in their pack. You can specify more images than you would actually be able to fit into your chosen product here, upto 200 images. Let's look at what needs to be defined for the chooser:

• product_type - This is the type of product that you'd like to make. Options are: minicard, sticker and postcard. Mandatory.
  NOTE: - Certain product types are not supported depending on the 'store' that you are accessing. Currently stickers are not available in the United States..
• url - The location of the image file you wish to use (see image url notes). Mandatory. See notes about images.

And that as they say is that... For that type of request at least. Next, we'll go on to look at requests where we pre-select images for the user and also supply cropping data for them. But, before we do, there's something you should know about image URLs...

Image URL notes: In order to avoid importing the same file over and over again every time you run your XML against this system, we store the URL that we picked the image up from, so if we see it again, we don't bother downloading it again. Can you see where this is going? Yup, if you change the image but use the same URL as a previous one that you've submitted to us, we won't pick up the new one, so remember to keep those URLs unique! You might also want to know that we currently only accept gifs, pngs and jpegs.

Image notes: Currently we support GIF, JPEG and PNG images at a minimum resolution of 300px x 300px.

Pre-selected images

Don't want to give the user some choice? Just want to get them on in there? Then you should have a look at the XML above. It allows you to drop a load of images directly into the making process for your given product type (in the example above it is stickers). The user will then be taken directly to the cropper page when they will be able to trim the image as they see fit. The request header is the same in this example (except we're not defining the return_to and fail_to elements so this will use the defaults). What has changed is the contents of the payload. Here, we've defined one product (all that is currently allowed) and in it we have:

• product_type - This is the same as the product type in the chooser. Mandatory.
• url - Again, this is a link to the image that you want. It obeys the same image rules as the chooser. Mandatory.
• type - The type is a fixed field at the moment and should always be set to variable. Mandatory

Pre-selected & cropped images

Things start to get a little bit more complex here. The above XML shows two different ways in which you can add cropping data to your images. You can mix and match these methods if you like, but you must either add cropping instructions for all images or none of them. We'll start with the easy one. By adding crop -> auto -> true to the image definition we will automatically add in the crop information for you based on the largest possible area that we can fit in the shape of the product that you want to make.

You can also specify your own crop data. For this you need to use the manual element:

• x & y - The top left co-ordinate of the cropping rectangle in pixels. Mandatory.
• width & height - The width and height of the cropping rectangle in pixels. Mandatory.

Cropping rules: You'll need to make sure that the cropping area you specify obeys the following rules:

1. The co-ordinates must be within the image.
   Where this gets more complex is that there is a certain amount of 'bleed' around the crop area. The bleed must not overlap with the outside of the image too. Bleed is different for each product. The trick is to stay out of the bleed area at the edge of the image. Here, have a look:
   • 
   • 
   • 
   You have to stay out of the green shaded area. It's easiest to think of this area as being n% of the shortest side of the image where n is, for:
   • minicard - 6%
   • sticker - 4%
   • postcard - 2%
2. The aspect ratio of the crop area must be the same as the product in question. The diagram below shows the aspect ratios of all our products.
   • 
   We're kind though. We'll let you be about 5% out and auto-correct the aspect if needs be.

Adding text

The XML above shows a simple definition of the text for the back of a minicard. The important thing to note is that in addition to the image definition in the design element there is also a text_collection element. This does not have be defined. Obviously, leaving it blank will mean that you don't want any text on the back of this particular card. If text is required, you then need to specify the type of text it is. Here, because we're making a minicard, we have added the minicard container. (The container element should always be the same as the content_type element or you'll get an error. Then, we define each text_line as show below

• id - The id of the text line that tells us where to place it on the back of the card. The IDs allowed are defined in the schema document. Links to examples of where the ids go are below.
• string - The text you want to add. As a general rule, if the id is a number, then the string can only be on one line.
• bold - This can either be true or false. If ommitted, the default is false
• align - This is either left, right or center. Some products only allow a subset of these. The default value is left unless otherwise stated in the schema.
• font - You can specify one of three fonts: modern (arial/helvetica), traditional (georgia) and typewriter (courier). The default is modern.
• colour - A hexidecimal string (with the #) for the colour of the line of text. The default is #000000 (i.e. black).

Some examples of text placement

Below are some example XML documents and PDF files of the text that they produce. It'll help you understand how the id relates to the position of the text for each product that we have text for.

• minicard - XML / PDF
• postcard - XML / PDF

Stage 2: Validating your XML

Once you've created your XML document, you should test it out to make sure that it's okay. We've made a little tool to help you with this. Simply drop the XML into the text box, check the 'is dev' check box and submit the XML. We'll have a peek at it and tell you if there's anything wrong with it. Simple!

You can also test out what would actually happen for the user by unchecking the 'is dev' box. This will parse the XML and then drop you into the design process as if you were a user. Doing this before you put the XML on your site has the added bonus of caching all the images that you wish to use in our system.

Stage 3: Putting it on your site

There are two methods you can use to now use the XML that you have created. They are the direct and browser methods. Both require you to post your document to http://uk.moo.com/en/api/api.php.

The browser method: This method uses the browser to do all the work and does not require server side scripting to communicate with our server. For this, all you need to do is to get the user to POST the XML to us. To do this you need to wrap the XML in a POST FORM. See below for an example

You may have spotted that all " characters have been encoded to " inside the hidden form element's value attribute. This is to keep the HTML legal. It's a bit of a pain, so we've written a little tool to escape the XML and drop the correct form element in around it.

The direct method: This method requires a little more effort on your part, but will be a little more familiar in operation to traditional APIs where you would send the request to our server yourself, receive a message back and then do what you need to for the user. In this case, either display an error or forward the user on to the correct page.

The XML that you send is exactly the same, this time, when you send POST data yourself, as well as specifying the xml with xml=bla you will also need to specify method=direct. By doing this, we know that you're talking to us, not a user's browser. All data returned will now come back as XML documents. There are two types that come back at the moment: An error or a success. We'll look at them now.

Above we see the error you would see if you sent malformed XML. The thing that let's us know that it's an error document is the <error>true</error> in the response header. It's all pretty self-explanatory. A success document is a little more fun.

Again, it's not rocket science. We've set up a session for the caller to pick up from. All you have to do is redirect then to the start_url and they're in business!

Err, that's it...

No, really, that's it.