Tutorial: getting started with the Personal Factory API in Python

Personal Factory is a cloud software platform for app developers to connect users directly to manufacturing devices to make custom goods on-demand.

It integrates product creation and customization apps with an established manufacturing and distribution system, so users can turn their designs into final products and have those products delivered to their door.

This is part one in a series of tutorials written by technologist Mark Schafer on working with the Personal Factory API in Python.

The full API documentation is here. All supplied examples use cURL.

The code for this tutorial can be found here: https://github.com/Neon22/Ponoko-API-from-python

Basic steps

Firstly we need to work out how to communicate with the sandbox created for us to play in without mucking up the proper site. To do that we have to use an authentication method to prove we are a legitimate user of the API.

There are three ways to authenticate yourself with Ponoko. Two of them are for using it yourself and the third allows you to add designs and products to other people’s (your clients?) accounts. This third method uses OAuth as the authentication method. We won’t be dealing with that here. Instead we will just be using the simple personal method.

We will use the “Simple access keys (for your own Personal Factory only)” which shows up under that heading in your application page.

All of this assumes you have registered an application with Ponoko and can see it under your “my apps” menu item on your personal page. This is where you will find these keys.

The API documentation page shows us a simple url showing how we can send a message to Ponoko to discover the manufacturing nodes available for us to use to create products. Onto this simple URL we need to add the authentication args.

Our simple authentication string is in this form (using your own values shown in your app page) looks like this:


The basic url looks like this:


Resulting in this:


We expect to get back a json format string containing useful info (defined one the API page). So lets try this in Python.


Firstly – our secret app keys (on your My apps page)

[gist id=1629879]

Sandbox vs Live

Secondly – we need to play in the safe sandbox until we get everything working. Then we’re going to want to switch to live. So we may as well make this easy now. The difference between the two is ‘www’ or ‘sandbox’ at the head of the URL.

[gist id=1629885]

We will switch comments when we go live.

Python – urllib2 and pycurl

In python there are several good ways to construct, send, and receive this information. The one I’m going to use is the urllib2 module. Later we will use pycurl for posting more complex multi-part forms.

In python we have:

[gist id=1629811]

This approach has the function get_manufacturing_nodes returning two values. Success and the nodes found. Many things can go wrong in http communications so we need to address that.

Lets define that function:

[gist id=1629913]

In the above function:

  1. We call it with the baseURL and the authentication key. We set verbose=True for debugging purposes. Later we’ll change this default to False.
  2. We construct the URL arguments manually as they are simple.
  3. Request has been imported from the urrllib2 module and formulates the request for us. When we call basic_request it will be actioned.
  4. The result is a success flag an dthe returned string from the Ponoko server.
  5. If the call failed we will see an error message in the result.
  6. If we succeeded then we wil hav the list of manufacturing nodes in json form in the result variable.
  7. So we extract them and report salient info on name and age for each manufacturing node if verbose.

Here is the function to perform basic http requests using urllib2. It detects the various exceptions likely to occur and returns correct codes. It also has its own verbose flag – which you can use to help see what it is doing or debug it.

[gist id=1630008]

It returns the error if it fails and a triplet of response, url, and info if successful. These may be useful for other purposes later. Primarily the response is all we need.

If we run this we should see a result like this:

[gist id=1630026]

If we had an error we might see this:

[gist id=1630033]

Showing us the only node in the sandbox is the USA hub, and when its materials were last updated. Once again – referring to the API docs is important to understand what to expect and what these fields are for.

We will use the last updated date to help us determine if we have to download a new materials catalog. If we did we could use a routine like the following to retrieve the product catalog to update our local store. (Which we are probably caching in our database.)

So we could change main to be:

[gist id=1630037]

Also lets add a dummy materials structure to check against. This would instead come from your database and you will have to make code changes to reflect the different structure.

[gist id=1630057]

You’ll also need to add this near the others at the top of the file:

[gist id=1630062]

So for each node we can check to see if it needs updating. So update_node_materials might look like this:

[gist id=1630064]

I’ve added a function called show_materials here to show what’s in the catalog and to save it. But you will need to update your own materials datastructure.

[gist id=1630069]

There’s a lot of data in the catalog – so I have chosen to only print out the names and some info about the cork materials. I also gathered the keys that were used. This might help me when designing a database to know which fields are mandatory. Other possible fields are commented out above. Consult the API docs for all of them.

We would want to use the updated_at field to help us only modify fields in our material structure that were out of date.

For questions about this tutorial or any questions about using the Personal Factory API, please visit the Ponoko Developer Forum.

Part 2 in this tutorial series: Uploading a product.

Mark Schafer is a technologist at Wireframe Ltd.
He has done some stuff. Like:
• wrote the first commercial single skinned skeletal animation system.
• worked in features, commercials, video games, and tech companies.
• motion captured Gollum for the LOTR films.
• been in a few startups (UK, USA, NZ), some more successful than others…
• makes Neon light sculptures… amongst other things.
• is building a 1m cubed 3D printer using icing sugar.
• has a sparsely populated store in the Ponoko showroom.