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:
- Web-based design app that posts designs to YouMagine
- Desktop application that helps you upload a project to YouMagine
- Javascript widget that showcases designs
Sample code:
- This Python code is used for allowing Ultimaker’s Cura to post to YouMagine: https://github.com/daid/Cura/blob/SteamEngine/Cura/util/youmagine.py
- PHP implementation: the official YouMagine SDK can be found here on GitHub
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:
- YouMagine should be a happy place. Respect the creators. People who have made a contribution to YouMagine deserve to be treated nicely. Please play well with them.
- YouMagine should be a tidy place. Don’t use the API to publish or diffuse spam through or on YouMagine. Please add things that will be of value to others. Specific, odd and niche items are just as welcome as common one-size-fits hits.
- We ask you to not in any way link directly to the 3D files of a design, but only link to the design on YouMagine.
- If the license requires it, you should include attribution for a design when displaying it somewhere.
- It is strictly forbidden to display a design with incorrect attribution. Presenting other people’s content as your own is not cool.
- Don’t use the API to mimic or clone core YouMagine functionality. Add value around it, don’t copy.
- Treat authorizations given to your application with respect. Only use the API to publish on behalf of users with their knowledge and consent. Please be clear, fair and transparent towards users about actions performed in their name on YouMagine. You’re encouraged to list your design tool or application appropriately. This can be done in the description or with the meta-data. Spamming with advertisement for a tool isn’t acceptable.
- If you enable someone to upload something to YouMagine through the API, always ask people to comply with the content policy. Among other things, let them only upload content to YouMagine to which they have the right to publish.
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 |