top

Make( options )

Returns an instance of the client library that interacts with a Make API server.

Parameters:
  • options (Object) - An object with the following attributes:
    • apiURL (String) - required - A valid URL pointing to the Make API server
    • apiPrefix (String) - A path to append the API URL, defaults to "/api/20130724/make/"
    • csrfToken (String) - An optional CSRF token to send in request headers (browser environments only)
    • hawk (Object) - Hawk credentials to be used for authentication. In order to Create, Update, Delete, Like and Unlike make records, you must provide auth. Without this, you will only be permitted to search for makes.
Example:
// without auth - Search only
var makeapi = new Make({
  apiURL: "http://makeapi.webmaker.org"
});

// with auth - Full CRUD functionality
var makeapiTwo = new Make({
  apiURL: "http://makeapi.webmaker.org",
  hawk: {
    // private key
    key: "00000000-0000-0000-000000000000",
    // public key
    id: "00000000-0000-0000-000000000000"
  }
});
top

find( options )

Build a make search based on the options argument

Parameters:
  • options (Object) - An object defining search types and terms to apply
Example:
var makeapi = new Make( optionsObj );

makeapi
.find({
  // search for two tags
  tags: [
    {
      tags: [ "awesome", "technology" ]
    }
  ],
  description: "kittens"
})
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

makeapi
.find({
  tags: [
    {
      tags: [ "awesome", "technology" ]
    },
    // filter for makes *without* the tags above
    false
  ],
  description: "kittens"
})
.then(function( err, makes ) {
  // handle response
});
top

matchAll( term [, options] )

Search for a term in many Make fields

Parameters:
  • term (String) - A search term to look for. it is applied on the following fields: author, contentType, description, id, remixedFrom, tagPrefix, tags, title, url, user
  • options (Object) - An optional Object defining settings for the search:
    • no_or (Boolean) - set to true to run the query with AND execution for the field terms
    • ignore (String or [String] - A string or array of strings defining which fields to not search the term against.
    • negateFields (String or [String] - A string or array of strings defining which fields should have "not" filters applied. i.e. "title is not 'foo'"
Example:
var makeapi = new Make( optionsObj );

makeapi
.matchAny( "foo" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

makeapi
.matchAny( "foo", {
  no_or: true
})
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

makeapi
.matchAny( "foo", {
  ignore: [ "url", "title", "tagPrefix" ]
})
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

makeapi
.matchAny( "foo",{
  ignore: "user",
  negateFields: [ "description", "url", "title" ]
})
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

contentType( type [, not ] )

Match Makes with the given content type value

Parameters:
  • type (String) - The content type value to search for
  • not (Boolean) - if true, only makes that do not match type
Examples:
var makeapi = new Make( options );

makeapi
.contentType( "application/x-thimble" )
.then(function( err, makes ) {
if ( err ) {
  // handle error case
}
// handle success!
});

// reverse the filter logic!
makeapi
.contentType( "application/x-thimble", true )
.then(function( err, makes ) {
if ( err ) {
  // handle error case
}
// handle success!
});
top

description( description [, not ] )

Match Makes with the given description text

Parameters:
  • description (String) - The description text to search for
  • not (Boolean) - if true, only makes that do not match description
Example:
var makeapi = new Make( options );

makeapi
.description( "maker party" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

// reverse the filter logic!
makeapi
.description( "maker party", true )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

id( id [, not ] )

Match Makes with the given ID

Parameters:
  • id (String) - The ID value to search for
  • not (Boolean) - if true, will match all makes except the one with the given id
Example:
var makeapi = new Make( options );

makeapi
.id( "makeID" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

// reverse the filter logic!
makeapi
.id( "makeID", true )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

remixedFrom( makeID [, not ] )

Match Makes with the given Make ID set as their remixedFrom value

Parameters:
  • makeID (String) - The Make ID that search hits must have set as their remixedFrom value
  • not (Boolean) - if true, only makes that do not match remixedFrom
Example:
var makeapi = new Make( options );

makeapi
.remixedFrom( someOtherMake.id )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

// reverse the filter logic!
makeapi
.remixedFrom( someOtherMake.id, true )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

sortByField( field [, direction ] )

Sort the makes matched By Elastic Search using the specified field and direction. Can be called multiple times to add more than one sort field, with the first fields taking precedence.

Parameters:
  • field (String) - A String matching one valid field of a make. i.e. "createdAt"
  • direction (String) - Either "asc" or "desc", specifying ascending or descending sort, respectively. defaults to "asc"
Example:
var makeapi = new Make( options );

makeapi
.sortByField( "updatedAt" )
.then(function( err, makes ) {});

makeapi
.sortByField( "createdAt", "desc" )
.sortByField( "updatedAt", "asc" )
.then(function( err, makes ) {});
top

tags( options [, not ] )

Add a filter to the search for the specified tag[s]

Parameters:
  • options (Object || Array) - An Object or Array. If it is an Array, it should contain one or all of the tags you wish to filter against. If it is an object, it must contain the following:
    • tags (Array) - An Array of tags, specified as strings
    • execution (String) - can be one of "and" and "or" Specifies if multiple tags should be searched for using AND/OR logic. defaults to "and". I.E. "tag1" OR "tag2"
    • **YOU MUST USE THE OBJECT STYLE DEFINITION WITH find
  • not (Boolean) - if true, only makes that do not match the given tag[s]
Example:
var makeapi = new Make( options );

makeapi
.tags( [ "foo", "bar", "baz" ] )
.then(function( err, makes ) {});

makeapi
.tags({
  tags: [ "foo", "bar", "baz" ]
})
.then(function( err, makes ) {});

makeapi
.tags({
  tags: [ "foo", "bar", "baz" ],
  execution: "or" // defaults to "and"
})
.then(function( err, makes ) {});
top

tagPrefix( prefix [, not ] )

Add a filter to the search for the specified prefix. for example, this will match makes with the tag "applePie" if prefix is "apple"

Parameters:
  • prefix (String) - A string specifying the prefix you wish to filter for. i.e. It will match "abc" in "abc:def"
  • not (Boolean) - if true, only makes that do not match prefix
Example:
var makeapi = new Make( options );

makeapi
.tagPrefix( "apple" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

// reverse the filter logic!
makeapi
.tagPrefix( "apple", true )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

title( title [, not ] )

Filter for makes matching the title - this is a full text search, so "maker party" will match "best maker party ever!"

Parameters:
  • title (String) - A String defining the title search value
  • not (Boolean) - if true, only makes that do not match title
Example:
var makeapi = new Make( options );

makeapi
.title( "application/x-thimble" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

// reverse the filter logic!
makeapi
.title( "application/x-thimble", true )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

user( username [, not ] )

Add a filter to the search for the specified username

Parameters:
  • username (String) - A string containing the username of the Webmaker whose Makes you want to filter for
  • not (Boolean) - if true, only makes that do not match username
Example:
var makeapi = new Make( options );

makeapi
.user( "amazingWebmaker" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});

makeapi
.user( "amazingWebmaker", true )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

likedByUser( username )

Filter for makes that the given user has liked

Parameters:
  • username (String) - A String representing the username of the Webmaker whose liked makes you wish to search for
Example:
var makeapi = new Make( options );

makeapi
.likedByUser( "webmaker" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

getRemixCounts()

Instructs the MakeAPI Server to include each make's remix count value in the search results. NOTE: This option can increase the response time of the request

Example:
var makeapi = new Make( options );

makeapi
.getRemixCounts()
.tags( "makerparty" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
  console.log(makes[0].remixCount);
});
top

or()

Changes the boolean logic applied to search filters from AND to OR

Example:
var makeapi = new Make( options );

makeapi
.or()
.description( "kittens and stuff" )
.title( "chainsaws" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

limit( num )

Sets the maximum number of results you want back from the Make API server. Defaults to 10

Parameters:
  • num (Number) - A whole number, greater than 0. If the value is rejected, it will not set limit and fail silently.
Example:
var makeapi = new Make( options );

makeapi
.limit( 20 ) // it can also convert the string "20" to a number
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

page( num )

Request a specific page of results. If the page is too high to contain matched makes, an empty array is returned

Parameters:
  • num (Number) - A whole number, greater than 0. If the value is rejected, it will not set limit and fail silently.
Example:
var makeapi = new Make( options );

makeapi
.page( 5 )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  // handle success!
});
top

create( options, callback )

Create a new Make

Parameters:
  • options (Object) - An Object defining a make. it should have the following attributes:
    • make (Object) - An object representing a new Make to create
  • callback (Function) - a function to execute when the server completes or fails to create the make
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.create({
  make: {
    url: "http://somewhere.com/makeurl"
    editurl: "http://webmakerapp.org/makeurl/edit",
    remixurl: "http://somewhere.com/makeurl/remix",
    title: "A make title",
    description: "this is a make",
    email: "webmakeruser@fakeemail.com",
    contentType: "application/x-app",
    thumbnail: "http://thumbnails.net/makethumbnail.png",
    published: true
  }
}, function( err, newMake ) {
  if( err ) {
    // something went horribly wrong
  }
  // newMake is your shiny new make!
});
top

update( id, options, callback )

Update a Make

Parameters:
  • id (String) - The ID of the make you want to update
  • options (Object) - An object containing any attributes of the make to be updated, with the values of each attribute being what to set
  • callback (Function) - a function to execute when the server completes or fails to update the make
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.update(
  "Make-ID",
  theObjectDefiningTheMake,
  function( err, updatedMake ) {
    if( err ) {
      // something went horribly wrong
    }
    // updatedMake is your updated make!
  }
);
top

remove( id, callback )

Delete a Make

Parameters:
  • id (String) - The ID of the make you want to delete
  • callback (Function) - a function to execute when the server completes or fails to delete the make
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.delete(
  "Make-ID",
  function( err, deletedMake ) {
    if( err ) {
      // something went horribly wrong
    }
    // the deleted make's data is in `deletedMake`
  }
);
top

like( id, maker, callback )

Like a Make

Parameters:
  • id (String) - The ID of the make the user wants to like
  • maker (String) - The email address associated with the Webmaker account that is liking a make. It is up to the consumer application to verify that they are dealing with a logged in user before issuing this API call
  • callback (Function) - a function to execute when the server completes or fails to like the make
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.like(
  "Make-ID",
  "webmakeruser",
  function( err, make ) {
    if( err ) {
      // something went horribly wrong
    }
    // success!
  }
);
top

unlike( id, maker, callback )

Unlike a Make

Parameters:
  • id (String) - The ID of the make the user wants to unlike
  • maker (String) - The email address associated with the Webmaker account that is unliking a make. It is up to the consumer application to verify that they are dealing with a logged in user before issuing this API call
  • callback (Function) - a function to execute when the server completes or fails to unlike the make
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.unlike(
  "Make-ID",
  "webmakeruser",
  function( err, make ) {
    if( err ) {
      // something went horribly wrong
    }
    // success!
  }
);
top

report( id, maker, callback )

Report a Make

Parameters:
  • id (String) - The ID of the make to report
  • maker (String) - The email address associated with the Webmaker account that is reporting a make. It is up to the consumer application to verify that they are dealing with a logged in user before issuing this API call
  • callback (Function) - a function to execute when the server completes or fails to report the make
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.report(
  "Make-ID",
  "webmakeruser"
  function( err, make ) {
    if( err ) {
      // something went horribly wrong
    }
    // success!
  }
);
top

cancelReport( id, maker, callback )

Cancel a report on a Make

Parameters:
  • id (String) - The ID of the make the to cancel a report on
  • maker (String) - The email address associated with the Webmaker account that is cancelling the report. It is up to the consumer application to verify that they are dealing with a logged in user before issuing this API call
  • callback (Function) - a function to execute when the server completes or fails to cancel the report
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.cancelReport(
  "Make-ID",
  function( err, make ) {
    if( err ) {
      // something went horribly wrong
    }
    // success!
  }
);
top

remixCount( id, options, callback )

Return the count of remixes for a given project in a given date range.

Parameters:
  • id (String) - The ID of the make to get a remixCount for
  • options (Object) - options for the remixCount call:
    • from (Number) - Unix style timestamp indicating the start date for the remix count query. If undefined, from is the date of the make's creation.
    • to (Number) - Unix style timestamp indicating the end date for the remix count query. The server's current time is used if undefined.
  • callback (Function) - A function to pass the result into
Example:
var makeapi = new Make( optionsObj );

// count remixes of the given project made between 7 and 3 days ago
makeapi
.remixCount(
  "idofthemake",
  {
    // 1 week ago
    from: Date.now() - ( 1000 * 60 * 60 * 24 * 7 )
    // three days ago
    to: Date.now() - ( 1000 * 60 * 60 * 24 * 3 )
  },
  function( err, result ) {
    if( err ) {
      // something went wrong
    }
    // Number of remixes!
    console.log( result.count );
  }
);
top

createList( options, callback )

Creates an ordered Make list with the given options

Parameters:
  • options (Object) - An Object with the following attributes:
    • makes (Array) - An Array of Make IDs
    • userId (Number) - The Unique user ID of the webmaker creating the list
    • title (String) - An optional title for the List - helps identifying the content of a list
  • callback (Function) - A function to pass the result into
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.createList(
  {
    makes: [ "123", "456", "789" ],
    userId: 12345
  },
  function( err, list ) {
    if( err ) {
      // something went wrong
    }
    // your new list!
    // NOTE: The list's makes will be represented as ID's in the response. To get the Make Data, request the list by ID using the GET route.
    console.log( list );
  }
);
top

updateList( id, options, callback )

Updates a Make list with the given options

Parameters:
  • id (String) - ID of the list that is to updated
  • options (Object) - An Object with the following attributes:
    • userId (Number) - The Unique user ID of the webmaker updating the list (must be list owner)
    • makes (Array) - An Array of Make IDs
    • title (String) - An optional title for the List - helps identifying the content of a list
  • callback (Function) - A function to pass the result into
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
.updateList(
  "id-of-a-list",
  {
    userId: 12345,
    makes: [ "123", "456" ]
  },
  function( err, list ) {
    if( err ) {
      // something went wrong
    }
    // updated list successfully!
    // NOTE: The list's makes will be represented as ID's in the response. To get the Make Data, request the list by ID using the GET route.
    console.log( list );
  }
);
top

removeList( id, userId, callback )

Deletes a List

Parameters:
  • id (String) - ID of the List to delete
  • userId (Number) - The Unique user ID of the webmaker deleting the list (must be list owner)
  • callback (Function) - A function to pass the result into
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
  .removeList(
    "id-of-a-list",
    12345,
    function( err, list ) {
      if( err ) {
        // something went wrong
      }
      // deleted list successfully!
      console.log( list );
    }
  );
top

getList( id, callback [, noWrap ] )

Get a List by ID

Parameters:
  • id (String) - ID of the list that is to retrieved
  • callback (Function) - A function to pass the result into
  • noWrap (Boolean) - optional boolean value. If set to true, the make data will not be passed through the wrap function of the makeapi-client
Example:
var makeapi = new Make( optionsObj );

makeapi
.getList(
  "id-of-a-list",
  function( err, listData ) {
    if( err ) {
      // something went wrong
    }
    console.log( listData ); // wrapped list data!
  }
).getList(
  "id-of-another-list",
  function( err, listData ) {
    // unwrapped list data
  },
  true // noWrap is true!
);
top

getListsByUser( userId, callback )

Get a Users lists

Parameters:
  • userId (Number) - ID of the user whose lists are to be retrieved
  • callback (Function) - A function to pass the result into
Example:
var makeapi = new Make( optionsObj );

makeapi
.getListsByUser(
  123,
  function( err, lists ) {
    if( err ) {
      // something went wrong
    }
    console.log( lists );
  }
);
top

appTags()

This function returns all application tags on a make. i.e. "webmaker.org:featured"

Example:
var makeapi = new Make( options );

makeapi
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }

  var appTags = makes[0].appTags();

  console.log( appTags );
});
top

userTags()

This function returns all user tags on a make. i.e. "webmakeruser@domain.com:favourite"

Example:
var makeapi = new Make( options );

makeapi
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }

  var userTags = makes[0].userTags();

  console.log( userTags );
});
top

rawTags()

This function returns all raw tags on a make. i.e. "teach"

Example:
var makeapi = new Make( options );

makeapi
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }

  var rawTags = makes[0].rawTags();

  console.log( rawTags );
});
top

taggedWithAny( tags )

Determine whether this make is tagged with any of the tags passed in

Parameters:
  • tags (String or [String]) - tag or tags to check this make for
Example:
var makeapi = new Make( optionsObj );

makeapi
.title( "teach kit" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  if( makes[0].taggedWithAny( [ "security", "privacy" ] ) ) {
    // has at least one of the tags!
  }
});
top

remixes( callback )

Get a list of other makes that were remixed from this make. The current make's URL is used as a key.

Parameters:
  • callback (Function) - a function to execute when the server responds to a search request. The function must accept two parameters: "( error, makes )" - if nothing went wrong, error will be falsy, and makes matching your search will be passed as the second parameter.
Example:
var makeapi = new Make( optionsObj );

makeapi
.title( "teach" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  makes[0].remixes(function( err, makes ) {
    // exactly like handling ".then()" callbacks
  });
});
top

locales( callback )

Similar to remixes(), but filter out only those remixes that have a different locale (i.e., are localized versions of this make).

Parameters:
  • callback (Function) - a function to execute when the server responds to a search request. The function must accept two parameters: "( error, makes )" - if nothing went wrong, error will be falsy, and makes matching your search will be passed as the second parameter.
Example:
var makeapi = new Make( optionsObj );

makeapi
.title( "teach" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  makes[0].locales(function( err, makes ) {
    // exactly like handling ".then()" callbacks
  });
});
top

original( callback )

Get the original make used to create this remix. Null is sent back in the callback if there was no original (not a remix)

Parameters:
  • callback (Function) - a function to execute when the server responds to a search request. The function must accept two parameters: "( error, makes )" - if nothing went wrong, error will be falsy, and makes matching your search will be passed as the second parameter.
Example:
var makeapi = new Make( optionsObj );

makeapi
.title( "Kittens" )
.then(function( err, makes ) {
  if ( err ) {
    // handle error case
  }
  makes[0].original(function( err, makes ) {
    // exactly like handling ".then()" callbacks
  });
});
top

update( email, callback )

This function will attempt to update a make.

Parameters:
  • email (String) - the email address of the maker updating the make
  • callback (Function) - a function to execute when the server responds to a search request. The function must accept two parameters: "( error, makes )" - if nothing went wrong, error will be falsy, and makes matching your search will be passed as the second parameter.
Example:
var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi
  .title( "teach" )
  .then(function( err, makes ) {
    if ( err ) {
      // handle error case
    }
    var make = makes[0];
    make.title = "New Title";
    make.update( "webmaker@webmaker.org", function( err, make ) {
      // handle results!
    });
  });