YouMagine API documentation

Introduction

YouMagine is about sharing and collaboration. We want YouMagine to be a platform for everybody and allow people to connect to YouMagine in various ways. This will allow more people to benefit from it and contribute to it. The API is a core part of YouMagine and has been the starting point of development. We believe that all apps are created equal. For example, Ultimaker’s Cura software uses the same API as everybody else can.

Applications:

Sample code:

Please let us know if you’ve written code that could serve as an example, so we can add this as an example here.

API etiquette

When using the APIs, we ask you to observe and comply with the following rules:

How to use the API

An application can request access to the YouMagine API on a per-user basis. This means the user will authorize the app to access YouMagine on his behalf. Once the link has been set up, the application can use YouMagine like the user would do. At any time, the user can revoke access of the application from his profile page. An application must first register with YouMagine before it can authorize for his users. To do this, the maintainer of the application should contact support@youmagine.com. Once YouMagine has registered the application, it can start giving users access.

To let a user authorize the app, use a web browser and let the user go to;

Request:

GET https://youmagine.com/integrations/{application}/authorized_integrations/new?redirect_url={redirect_url}&deny_url={deny_url}

When your app is not authorized (because the user clicks “Deny”), the user is redirected to deny_url.

When your app is authorized (because the user already allowed your app once, or the user clicks “Allow”), the user will be directed to redirect_url using POST. The following parameters will be sent along:

Param name Description
authentication_token
The authentication token that has to be sent with all requests
user
JSON encoded user data, comparable to /v1/users/:id
authorized_integration
JSON encoded info about the authorized session for this user (for debugging purpose only, no guarantees for this parameter)

Resources

Designs API to retrieve or modify designs

Resource Description
GET /v1/designs/search Search for designs
GET /v1/designs Load all published designs
GET /v1/designs/:id Load a specific design by ID or slug
POST /v1/designs Create a new design
PATCH /v1/designs/:id Update a design
PUT /v1/designs/:id Update a design
DELETE /v1/designs/:id Delete a single design

Documents API to retrieve or modify a design's documents

Resource Description
GET /v1/designs/:design_id/documents Load all documents of a design
GET /v1/designs/:design_id/documents/:id Load a specific document of a design by ID
POST /v1/designs/:design_id/documents Create a document for a design
PATCH /v1/designs/:design_id/documents/:id Update a design's document
PUT /v1/designs/:design_id/documents/:id Update a design's document
DELETE /v1/designs/:design_id/documents/:id Delete a single document of a design

Images API to retrieve or modify a design's images

Resource Description
GET /v1/designs/:design_id/images Load all images of a design
GET /v1/designs/:design_id/images/:id Load a specific image of a design by ID
POST /v1/designs/:design_id/images Add an image to a design
PATCH /v1/designs/:design_id/images/:id Update a design's image
PUT /v1/designs/:design_id/images/:id Update a design's image
DELETE /v1/designs/:design_id/images/:id Delete a single image

Users API to retrieve users

Resource Description
GET /v1/users/:user_id/users Load all users
GET /v1/users Load all users
PUT /api/users/whoami
GET /v1/users/:user_id/users/:id Load a specific user by ID or slug
GET /v1/users/:id Load a specific user by ID or slug
GET /v1/users/:id/designs Load all the designs of an user
GET /v1/users/:user_id/users/:id/designs Load all the designs of an user