Getting Started

This How To Guide will take you through the steps necessary to create a working Shapeways App. You'll start by registering an account and an application. The next step is to authenticate using OAuth. Once authenticated, we'll take you through the Upload API, the Pricing API, and the Checkout API.


Documentation

We've created two types of documentation for the Shapeways 3D Printing API:

Register on Shapeways

If you don't already have a Shapeways account, register your user profile.


Register a Shapeways Application

Visit the Manage Apps section of http://www.shapeways.com by hovering over your username in the site navigation and clicking Manage Apps (Note: you must be logged in).

From the Manage Apps screen, you can create, edit, or delete your applications. To create a new app, click the 'Create a New App' button in the upper right corner.

Application Name: Choose a title for your Shapeways App - this title may be shown during authentication, in Shapeways App Gallery, and on products that are generated using your app.

Application Website: Enter a link to the location of your application - this link will be used to direct users from the Shapeways App Gallery, and on products that are generated using your app.

Application Description: Write a description of your application - describe the types of products your app will create, why your app is unique, and any other information you'd like people to know.

Application Photo: Upload a 75x75px thumbnail for your application - this image will be displayed next to your application name during authentication, in the Shapeways App Gallery, and on products that are generated by using your app.


OAuth Settings

Once you've created your application, you will be taken to a dedicated page where you can retrieve your API Keys. Your Consumer Key and Consumer Secret are unique identifiers that allow your application to access Shapeways data. Your app's API key and secret are private and should be kept in a secure location.


Authenticate via the API

In order to create models or do other user-facing activities on Shapeways, your application will need to access a user's Shapeways account. Shapeways uses a standard protocol for authenticating users called OAuth 1.0. You can read more about OAuth here: http://tools.ietf.org/html/rfc5849

User Authentication follows a series of requests between the user's browser, your app, and the Shapeways API, with the ultimate goal being a valid ‘access token' and ‘access token secret' for that user. These two tokens must be passed with each request for a ‘protected resource' with the Shapeways API. You can read more about different types of OAuth keys here: http://oauth.net/core/1.0/#anchor3

See the following diagram for a typical Authentication Flow: Authentication Flow

For these examples, we'll be using PHP. You will find other API reference clients and example code on Github

The Shapeways API PHP reference client is hosted on Github. There is a specific example for creating an access token.

Here's a PHP example of OAuth authentication:

      $oauth_client = new Oauth(
        $consumer_key,
        $consumer_secret,
        OAUTH_SIG_METHOD_HMACSHA1,
        OAUTH_AUTH_TYPE_AUTHORIZATION
      );
      $info = $oauth_client->getRequestToken(
        "$api_url_base/oauth1/request_token/v1",
        "oob"
      );
    

Next we set the token into the OAuth client:

    $oauth_client->setToken(
      $info['oauth_token'],
      $info['oauth_token_secret']
    );
  

Finally, we get our access token:

      $pin = readline("Pin: ");
      $info = $oauth_client->getAccessToken(
        "$api_url_base/oauth1/access_token/v1",
        null,
        $pin
      );
      $oauth_client->setToken(
        $info['oauth_token'] ,
        $info['oauth_token_secret']
      );
    

You can use the same OAuth Request Token and OAuth Request Token Secret until they expire so you may want to store these to avoid authenticating the same user many times.


Upload and Sell Products

To create a new product on Shapeways you need a 3D model - here are the details from our Create Product page:

Uploading 3D files: Maximum size: 64 MB or 1 million polygons
Filetypes: DAE, OBJ, STL, X3D, X3DB, X3DV, WRL
Color printing: DAE, WRL, X3D, X3DB, X3DV
For textures: GIF, JPG, PNG
ZIP: Containing filetypes above
Privacy: Product will be private by default
The binary or text contents of the 3D Model file or zip file should be base64 encoded and then url encoded as part of the POST request.

    $filename = "cube-1cm3-centered_in_meter.stl";
    $file = file_get_contents("../models/". $filename);
    $data = array(
      "fileName" => "$filename",
      "file" => rawurlencode(base64_encode($file)),
      "hasRightsToModel" => 1,
      "acceptTermsAndConditions" => 1,
    );
    $data_string = json_encode($data);
    $oauth->fetch(
      $api_url_base ."/models/v1",
      $data_string,
      OAUTH_HTTP_METHOD_POST
    );
    $response = $oauth->getLastResponse();
    $json = json_decode($response);
  

Here's what the response looks like:

    {
      "result":"success",
      "fileName":"cube-1cm3-centered_in_meter.stl",
      "contentLength":28335,
      "fileMd5Checksum":"c6e6872e09ff954d1e44292aac6d594a",
      "modelId":1234567,
      "modelVersion":0
    }
  

To make a model public and for sale, you can make a PUT request like this:

    $modelId = 1234567; // use modelId from model upload response
    $data = array(
      "isPublic" => 1,
      "viewState" => 1,
    );
    $data_string = json_encode($data);
    $oauth->fetch(
    $api_url_base ."/models/". $modelId . "/info/v1/",
      $data_string,
      OAUTH_HTTP_METHOD_PUT
    );
    $response = $oauth->getLastResponse();
    $json = json_decode($response);
  

Here's what the response looks like:

{
    "result":"success",
    "modelId":1234567,
    "modelVersion":0,
    "title":"MyFavoriteModel",
    "description":"", 
    "isPublic":1,
    "isForSale":1
}      
    
  

Instant Pricing

Here's how to get a price for any 3D geometry:

    $volume = 1 / (100*100*100); // 1 cm^3 in m^3
    $area = 600 / (1000*1000); // 600 mm^2 (6 cm^2) in m^2
    $xBoundMin = -0.01; // 1 cm in m
    $yBoundMin = -0.01;
    $zBoundMin = -0.01;
    $xBoundMax = 0.01;
    $yBoundMax = 0.01;
    $zBoundMax = 0.01;
    $materials = array(6, 25);
    $data = array(
      "volume" => $volume,
      "area" => $area,
      "xBoundMin" => $xBoundMin,
      "xBoundMax" => $xBoundMax,
      "yBoundMin" => $yBoundMin,
      "yBoundMax" => $yBoundMax,
      "zBoundMin" => $zBoundMin,
      "zBoundMax" => $zBoundMax,
      "materials" => $materials,
    );
    $data_string = json_encode($data);

    $oauth->fetch(
      $api_url_base ."/price/v1",
      $data_string,
      OAUTH_HTTP_METHOD_POST
    );
    $response = $oauth->getLastResponse();
    $json = json_decode($response);
  

Here's what the response looks like:

{
    "result":"success",
    "prices":
    {
        6:{
                "materialId":6,
                "price":2.9,
                "currency":"USD"
          },
       25:{
                "materialId":25,
                "price":3.5,
                "currency":"USD"
          }
    },
    "nextActionSuggestions":
    {
        "uploadModel":
        {
            "method":"POST",
            "restUrl": "http://api.shapeways.com/model/v1",
            "link":"/model/v1"
        }
    }
}

  

Checkout and 3D Print

Here's how to add a model into the Shapeways shopping cart:

      $modelId = 1234567; // use modelId from model upload response
      $data = array(
        "modelId" => "$modelId",
        "materialId" => 6,
        "quantity" => 1,
      );
      $data_string = json_encode($data);
      $oauth->fetch(
        $api_url_base ."/cart/v1",
        $data_string,
        OAUTH_HTTP_METHOD_POST
      );
      $response = $oauth->getLastResponse();
      $json = json_decode($response);
    

Advanced Topics

Printability

We automatically check all uploaded 3D models to ensure that they will withstand the 3D Printing process and end up as high quality products that you can hold and treasure. These automatic checks assess the basic requirements for printability. Some 3D geometries that pass our automated checks are later found to be too fragile or impossible to 3D Print. If you are purchasing your own creations, we will work with you to achieve consistent printability from your application. If you are selling products to others in the Shapeways community we may disable your application from publishing products until all printability issues are resolved.

To limit any disruption to the availability of your app, we recommend testing variants of the products created by the app in the material(s) in which you plan to offer it to ensure they meet our design guidelines. Here's how to test:

  1. Generate multiple variants of the product created by your app in order to get a good sampling of the end quality.
  2. Order the products in the materials you plan to promote alongside the app.
  3. Check and refine! Keep testing until you feel confident all potential users will have printable files that meet expectations.

Ask yourself these questions about quality:

  1. Does the end product match a customer's expectations based on what's generated digitally?
  2. Is it compelling and interesting and people will want to own it?
  3. Do the materials in which you offer the product make sense for function, and form?

If you create an app that does not meet our design guidelines, the products might be rejected or disappoint your end customer.

We reserve the right to disable an App at any time for any reason. We will always inform and discuss the reasons for deactivation. Primary reasons for disabling an App include: content policy violation, printability issues, manufacturing limitations.

Manufacturing Limits

Shapeways handles all aspects of manufacturing your product including post-processing, handling, and shipping. There are some limitations to this process which can negatively affect customer experience and cause your application to be removed. We are committed to high quality products and innovation and we will work with you to the best of our ability to address any issues found in manufacturing.

Color Models

We fully support 3D models that use color or textures and can 3D print your products in our full color materials. To create a full color product, upload a ZIP file containing a .wrl file and all necessary textures.

Large 3D Models

Shapeways has a 64MB limit on file size and a 1,000,000 on the number of polygons we'll accept in a single upload. Often times 3D Models contain detail that is far beyond the print resolution - there are many techniques for reducing detail that will not affect the resulting printed product.

Customizing Geometry

There are several 3D geometry generation libraries available:


Restricted Content

Some content is prohibited on Shapeways and will be removed. A full list of this content can be found in our content policy.

Beta Features

All new API features will spend some time in a beta period. Beta features are marked as Beta in the API HTML documentation as will as in the JSON API discovery. To access a beta feature, add a GET parameter 'beta=true' to an API request. An attempt to access a beta uri+method without the beta flag set will result in an error being returned. Beta parameters sent to the API without the beta flag set will be ignored.

Please note that beta features are available for you to experiment with before they are officially supported. Functionality, naming schemes, and the like for beta features are subject to change without notice. Beta features should not be used in production applications.