DIY

Make applications with DIY

 

Getting Started

DIY's API is open for use by any institution or individual. We only ask that you follow the content guidelines and other terms found in our TOS. If you have any feature requests or questions about our roadmap, please let us know.

A Basic Request

curl https://api.diy.org
{
        "head": {
            "code": 200,
            "status": "OK",
            "collection": {
                "limit": 20,
                "offset": 0
            }
        },
        "response": {
            "docs": "docs.diy.org",
            "help": "help@diy.org",
            "twitter": "@diy"
        }
    }

Response Format

API responses are always returned using the following format:

{
        "head": {
            "code": [HTTP response code],
            "status": [HTTP response message],
            "collection": [Pagination details]
        },
        "response": {
            [Response object]
        }
    }

Limits & Pagination

Resources that return an array of objects support limits and pagination. These parameters may be passed to the API using the "limit" and "offset" query variables respectively. For example, the following cURL command will return the first 2 results from the /skills resource:

curl "https://api.diy.org/skills?limit=2&offset=0"

API Versioning

It is recommended that API users declare the "Accept-Version" header prior to deploying any application to production. The current API version is 3.3.1 and follows semantic versioning conventions.

curl -H "Accept-Version:~3.3" https://api.diy.org/skills

Authentication

Maker accounts are authenticated using Basic Authentication over HTTPS:

curl -u "someuser:password" https://api.diy.org/authorize

The authorize method returns an access token that can be used as the key to generate an SHA1 HMAC token for subsequent requests by using the provided maker "url". Once generated, future requests can be signed as:

curl -H "x-diy-api-token:HMACTOKEN" https://api.diy.org/makers/something

Rate Limits & Bursting

The API enforces a rate limit of approximately 10 requests/sec per IP. Bursting is provided as a convienence, but continuous usage above the rate limit may result in the API returning a 429 status code. If you feel that your application may need an exception to this rate limit, please contact us.

Resources

authorize

authorize - Returns maker authorization information

Method URI Description
get /authorize Returns an authorization object including HMAC token, maker ID and type information

achievements

achievements - Achivements represent completed and pending challenge solutions for a maker.

Method URI Description
get /makers/:id/achievements Returns the specified maker's achievements.
post /makers/:id/achievements Creates a new maker achivement for the specified project and challenge id.
project
challenge

challenges

challenges - A challenge represents a single task towards earning a skill.

Method URI Description
get /skills/:id/challenges Returns a list of all challenges for the specified skill.
get /skills/:id/challenges/:id Returns a single challenge by id.

clips

clips - A clip represents a single piece of media from a maker related to a project.

Method URI Description
get /makers/:id/projects/:id/clips Returns an array of clips for the specified project instance.
post /makers/:id/projects/:id/clips Creates a new clip for the specified project.
type
put /makers/:id/projects/:id/clips/:cid Updates a specified clip.
delete /makers/:id/projects/:id/clips/:cid Deletes a specified clip.

comments

comments - A comment represents a single text object from a maker related to a project.

Method URI Description
get /makers/:id/projects/:id/comments Returns an array of comments for the specified project instance.
post /makers/:id/projects/:id/comments Creates a new comment for the specified project.
raw
reply [optional]
put /makers/:id/projects/:id/comments/:cid Updates a specified comment.
raw
reply [optional]
flag [optional]
delete /makers/:id/projects/:id/comments/:cid Deletes a specified comment.

examples

examples - An example represents a reference or guide for completing a challenge.

Method URI Description
get /skills/:id/challenges/:id/examples Returns a list of all examples for the specified skill.
get /skills/:id/challenges/:id Returns a single example by id.
post /skills/:id/challenges/:id/examples Creates a new example for the specified skill and challenge.
put /skills/:id/challenges/:id/examples/:id Updates a example for the specified skill and challenge.
delete /skills/:id/challenges/:id/examples/:id Removes a example for the specified skill and challenge.

explore

explore - Explore provides lists of featured and/or trending projects in the community.

Method URI Description
get /explore/featured Returns a list of featured projects.
get /explore/introducing Returns a list of new 15 second intro videos.
get /explore/trending Returns a list of trending projects.

favorites

favorites - Favorites represent projects that have been selected by a maker.

Method URI Description
get /makers/:id/favorites Returns the specified maker's favorite projects.
get /makers/:id/projects/:id/favorites Returns all makers who have favorited the specified project.
post /makers/:id/projects/:id/favorites Creates a new favorite for the specified project.
project
delete /makers/:id/projects/:id/favorites Removes a favorite for the specified project.
project

friends

friends - Friends represent makers that have been either followed or are following a maker.

Method URI Description
get /makers/:id/followers Returns list of followers for the specified maker.
get /makers/:id/following Returns list of followed makers.
post /makers/:id/following Adds a new follower.
maker
delete /makers/:id/following Removes a follower.
maker

makers

makers - A maker represents a single child user within the DIY ecosystem.

Method URI Description
get /makers/:id Returns the specified maker instance.
post /makers Creates a new maker instance.
nickname
password
species
parent
put /makers/:id Updates the specified maker instance.

open badges

open badges - Badges and assertions represent the Open Badges Initiative (OBI) form of DIY skill patches.

Method URI Description
get /makers/:id/assertions Returns the specified maker's badge assertions.
get /makers/:id/assertions/:id Returns the specified assertion instance.
get /skills/:id/badge Returns the specified badge instance.
get /organization Returns the DIY organization metadata for OBI.

projects

projects - A project represents a collection of unique shots of various media types from a maker.

Method URI Description
get /makers/:id/projects Returns the specified maker's projects.
get /makers/:id/projects/:id Returns the specified project instance.
post /makers/:id/projects Creates a new project instance.
title
put /makers/:id/projects/:id Updates the specified project instance.
delete /makers/:id/projects/:id Deletes the specified project instance.

skills

skills - A skill represents a set of challenges, references, and materials that relate to a theme.

Method URI Description
get /skills Returns all skills.
get /skills/:id Returns the specified skill instance.

materials

materials - A material represents a single tool or object that can be used to complete a challenge.

Method URI Description
get /skills/:id/materials Returns a list of all materials for the specified skill.

Sandbox

 


Data Types

achievement -

Property Type Description
id int Unique achievement id.
status string Achievement status. Enumerated: "pending", "approved", "rejected".
stamp date Achievement creation date.
skill skill Skill related to the achievement.
challenge challenge Challenge related to the achievement.

asset -

Property Type Description
url string Absolute URI to media asset.
mime string Mime-type of media asset.
width int Width of media asset in pixels.
height int Height of media asset in pixels.
size int Size of asset in bytes.

challenge -

Property Type Description
id int Unique challenge id.
active boolean Active state for the challenge.
title string Full title for the challenge.
short string Short title for the challenge.
description string Challenge description.
stats object Aggregate statistics for the challenge.
difficulty [int]
danger [boolean]
image asset "Hero" assets that best describe the challenge

clip -

Property Type Description
id int Unique clip id.
type string Clip media type. Enumerated: ['image', 'video']
assets asset Clip assets for display.

comment -

Property Type Description
id int Unique comment id.
stamp time Comment creation date.
reply int If reply, unique id of original comment.
flagged boolean Comment flag state. E.g.: Has comment been flagged?
reviewed boolean Comment review state. E.g.: Has comment been reviewed by an admin?
raw string Comment in "raw" markdown format.
html string Comment in pre-rendered HTML format.
maker maker Maker information of the comment author.

example -

Property Type Description
id int Unique example id.
title string Example title.
source string Example source attribution.
tag string Example classification tag.
url string Absolute URI to the example's source.
assets asset Example display assets.

maker -

Property Type Description
id int Unique maker id.
stamp time Maker account creation date.
url string Url-encoded version of the maker's nickname.
nickname string Makers nickname used for display.
type object Describes a members's permissions.
moderator [boolean]
adult [boolean]
subscriber [boolean]
verified [boolean]
suspended [boolean]
avatar asset Avatar assets for the maker.
portfolio object Portfolio display settings for the maker.
bio [string]
foreground [color]
background [color]
stats object Aggregate statistics for the maker.
projects [int]
achievements [int]
patches [int]
following [int]
followers [int]

material -

Property Type Description
id int Unique material id.
stamp date Material creation date.
title string Material name.
link string Absolute URI to material information.

project -

Property Type Description
id int Unique project id.
stamp time Project creation date.
title string Project title.
stats object Aggregate statistics for the project.
featured [boolean]
favorites [int]
comments [int]
achievements [int]
maker maker Maker information for project owner.
clips clip An array of clips.

skill -

Property Type Description
id int Unique skill id.
url string Url-encoded skill name.
sku int SKU identifier for the skill in DIY's Market.
stamp time Skill launch date.
active boolean Active state for the skill.
title string Skill title.
description string Description of the skill.
position int Vector "point" for the skill's position in the grid.
icons object Skill icon URIs at various resolutions.
small [string]
medium [string]
images object Skill artwork URIs at various resolutions.
small [string]
medium [string]
large [string]
grammar object Parts of speech used when describing the skill.
singular [string]
plural [string]
subject [string]
article [string]