hawk - optional - 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.

Searching

then( callback )###

Execute the search that has been built. Once the search data has been sent to the server, the make object will be cleared and ready to build another search.

callback a function to execute when the server responds to a search request. The function must accept two or three parameters: ( error, makes [, total ] ) - if nothing went wrong, error will be null, and makes matching your search will be passed as the second parameter. The optional third parameter is the total number of matched hits that Elastic Search found. This may be equal to or greater than the array of makes returned.

Example###

var makeapi = new Make( optionsObj );

// Executing `then` without specifying any search filters will return the first 10 makes

// that the MakeAPI's Elastic Search cluster has indexed (so in no particular order).

makeapi.then(function( err, makes ) {

if( err ) {

// handle error case

}

// handle success!

});

// Executing `then` and passing in three parameters:

makeapi.then(function( err, makes, total ) {

if( err ) {

// handle error

}

// total can be used to determine if there are more pages to be fetched (see the `page` function)

});

find( options )###

Add filters to your search based on the attributes of the options parameter.

options - required - An object that can contain attributes corresponding to any other valid search function (see example below and other search function docs). The value of each search attribute can be a String or Array. If an array, the elements will be applied to the corresponding search function as arguments.

Tags is a special case in find, It will only work with an object definition. See the example below.

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

});

author( name, not )###

Add a filter to the search for the specified author.

name - required - A string containing the authors name
not - Boolean value that when set true, will force a filter for makes that Do Not contain the specified name

Example####

var makeapi = new Make( optionsObj );

makeapi

.author( "Mr. Anonymous" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

// I want makes where the author is NOT mr. Anonymous

makeapi

.author( "Mr. Anonymous", true )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

user( name, not )###

Add a filter to the search for the specified username.

name - required - A string containing the username of the maker you want to filter for
not - Boolean value that when set true, will force a filter for makes that Do Not contain the specified user

Example####

var makeapi = new Make( optionsObj );

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!

});

tags( options, not )###

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

options - 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 - required - An Array of tags, specified as strings

execution - optional - 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"

ONLY THE OBJECT STYLE DEFINITION WORKS WITH .find()

not - Boolean value that when set true, will force a filter for makes that Do Not contain the specified tags

Example####

var makeapi = new Make( optionsObj );

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 ) {});

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"

prefix - required - A string specifying the prefix you wish to filter for. i.e. It will match "abc" in "abc:def"not - Boolean value that when set true, will force a filter for makes that Do Not contain the specified prefix

Example####

var makeapi = new Make( optionsObj );

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!

});

limit( num )###

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

num - required - A whole number, greater than 0. If the value is rejected, it will not set limit and fail silently.

Example####

var makeapi = new Make( optionsObj );

makeapi

.limit( 20 ) // it can also convert the string "20" to a number

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

page( num )###

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

For Example: if a search is limited to 5 results but Elastic Search matched 10 makes, requesting page 2 would give you search hits numbered 5 to 9 (zero indexed)

num - required - A whole number, greater than 0. If the value is rejected, it will not set limit and fail silently.

Example####

var makeapi = new Make( optionsObj );

makeapi

.page( 5 )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

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.

field - required - A String matching one valid field of a make. i.e. "createdAt"
direction - optional - a String, either "asc" or "desc", specifying ascending or descending sort, respectively. defaults to "asc"

Example####

var makeapi = new Make( optionsObj );

makeapi

.sortByField( "updatedAt" )

.then(function( err, makes ) {});

makeapi

.sortByField( "createdAt", "desc" )

.sortByField( "updatedAt", "asc" )

.then(function( err, makes ) {});

url( makeUrl, not )###

Filter makes for a specific URL. URL is unique for makes, so it will match one make only. The result will still always be an array.

makeUrl - required - A String defining a url to filter on
not - Boolean value that when set true, will force a filter for makes that Do Not contain the specified URL

Example####

var makeapi = new Make( optionsObj );

makeapi

.url( "www.make.url.com/path/to/make.html" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

contentType( contentType, not )###

Filter makes by contentType.

contentType - required - A String defining a contentType to filter for
not - Boolean value that when set true, will force a filter for makes that Do Not contain the specified content type

Example####

var makeapi = new Make( optionsObj );

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!

});

remixedFrom( projectID, not )###

Filter for makes remixed from the project that has the specified project id

projectID - required - A String defining the project ID you are filtering for
not - Boolean value that when set true, will force a filter for makes that Are Not remixed from a make with the specified ID

Example####

var makeapi = new Make( optionsObj );

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!

});

id( id, not )###

Filter for a make with the specified ID

id - required - A String defining the project ID you are filtering for
not - Boolean value that when set true, will force a filter for makes that Do Not match the specified ID

Example####

var makeapi = new Make( optionsObj );

makeapi

.id( "SomeMakesIDValue" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

// reverse the filter logic!

makeapi

.id( "someMakesIDValue", true )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

title( title, not )###

Filter for makes matching the title - this is a full text search, so "Kittens" will match "I love Kittens!"

title - required - A String defining the title search value
not - Boolean value that when set true, will force a filter for makes that Do Not match the specified title

Example####

var makeapi = new Make( optionsObj );

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!

});

description( description, not )###

Filter for makes matching the description - this is a full text search, so "kittens and stuff" will match "a project about kittens and stuff!"

description - required - A String defining the description search value
not - Boolean value that when set true, will force a filter for makes that Do Not match the description

Example####

var makeapi = new Make( optionsObj );

makeapi

.description( "kittens and stuff" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

// reverse the filter logic!

makeapi

.description( "Kittens and stuff", true )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

likedByUser( username )###

Filter for makes that the given user has liked

username - required - A String representing the username

Example####

var makeapi = new Make( optionsObj );

makeapi

.likedByUser( "webmaker" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

or()###

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

Example####

var makeapi = new Make( optionsObj );

makeapi

.or()

.description( "kittens and stuff" )

.title( "chainsaws" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

});

getRemixCounts()###

Will tell the MakeAPI Server to hydrate 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( optionsObj );

makeapi

.getRemixCounts()

.tags( "makerparty" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

// handle success!

console.log(makes[0].remixCount);

});

Search Results

The Client Library wraps each make result in some API sugar for easy use. Call the following functions on individual make search results. i.e. makes[4].rawTags()

appTags()###

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

taggedWithAny( tags )###

tags - required - This can be a String or [ String ], and the logic is OR vs. AND for multiple.

Example####

var makeapi = new Make( optionsObj );

makeapi

.title( "Kittens" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

if( makes[0].taggedWithAny( ["kittens" ] ) ) {

// it was tagged!

}

});

remixes( callback )###

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

callback 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].remixes(function( err, makes ) {

// exactly like handling `then` callbacks

});

});

locales( callback )###

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

callback 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].locales(function( err, makes ) {

// exactly like handling `then` callbacks

});

});

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)

callback 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 ) {

// check for null!!

});

});

update( email, callback )###

Requires AUTH - This function will attempt to update a make.

email the email address of the maker updating the make
callback a function to execute when the server completes or fails to update the make

Example####

var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi

.title( "Kittens" )

.then(function( err, makes ) {

if ( err ) {

// handle error case

}

var make = makes[0];

make.title = "New Title";

make.update(function( err, make ) {

// handle results!

});

});

Each Wrapped Make will have the following attributes, which can be changed and then updated with the update method above:

url

contentType

locale

title

description

author

published

tags

thumbnail

username

remixedFrom

id

emailHash

createdAt

updatedAt

Create, Update & Delete

These functions require auth (see constructor docs)

create( options, callback )###

This function will attempt to create a make.

options - required - An Object defining a make. it should have the following attributes

maker - required - The email address of the maker

make - required - An object representing a Make. See the list of make attributes above.

callback - required - 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({

maker: "maker@makerland.org",

make: theObjectDefiningTheMake

}, function( err, newMake ) {

if( err ) {

// something went horribly wrong

}

// newMake is your shiny new make!

});

update( id, options, callback )###

This function will attempt to update a make.

** using the wrapped make update function documented above is recommended over this function **

id - required - The ID of the make you want to update

options - required - An object representing a Make. See the list of make attributes above.

callback 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(

"idofthemakeiwanttoupdate",

theObjectDefiningTheMake,

function( err, updatedMake ) {

if( err ) {

// something went horribly wrong

}

// updatedMake is your updated make!

}

);

delete( id, callback )###

This function will attempt to delete a make.

id - required - The ID of the make you want to delete

callback 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(

"idofthemakeiwanttoupdate",

function( err, deletedMake ) {

if( err ) {

// something went horribly wrong

}

// the deleted make's data is in `deletedMake`

}

);

like( id, maker, callback )###

This function will add the user to the target makes' like array.

id - required - The ID of the make the user wants to like

maker -- required 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 A function to execute when the server completes or fails to mark the make as liked

Example####

var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi

.like(

"idofthemakeiwanttoupdate",

function( err, updatedMake ) {

if( err ) {

// something went horribly wrong

}

// the make that was updated is in updatedMake

}

);

unlike( id, maker, callback )###

This function will remove the user from the target makes' like array.

id - required - The ID of the make the user wants to unlike

maker - required - The email address associated with the Webmaker account which wishes to unlike 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 A function to execute when the server completes or fails to mark the make as unliked

Example####

var makeapi = new Make( optionsObjWithAuth ); // this NEEDS auth

makeapi

.unlike(

"idofthemakeiwanttoupdate",

function( err, updatedMake ) {

if( err ) {

// something went horribly wrong

}

// the make that was updated is in updatedMake

}

);

remixCount( id, options, callback )###

This function will return the count of remixes for a given project in a given date range.

id - required - The ID of the make

options - An optional Object defining a make. it should have the following attributes

from - Unix style timestamp indicating the start date for the remix count query. If undefined, from is ignored.

to - Unix style timestamp indicating the end date for the remix count query. The server's current time is used if undefined.

callback - required - 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 );

}

);

createList( options, callback )###

Creates an ordered Make list with the given options

options - required - it should have the following attributes

makes - required - An Array of Make IDs

userId - required The Unique user ID of the webmaker creating the list

title - An optional title for the List - helps identifying the content of a list.

callback - required - A function to pass the result into

Example####

var makeapi = new Make( optionsObj );

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.

title - An optional title for the List - helps identifying the content of a list.

callback - required - A function to pass the result into

Example####

var makeapi = new Make( optionsObj );

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 );

}

);

removeList( id, userId, callback )###

Deletes a Make list with the given options

id - required - ID of the list that is to updated
userId - required - The Unique user ID of the webmaker deleting the list
callback - required - A function to pass the result into

Example####

var makeapi = new Make( optionsObj );

makeapi

.updateList(

"id-of-a-list",

12345,

function( err, list ) {

if( err ) {

// something went wrong

}

// deleted list successfully!

console.log( list );

}

);

getList( id, callback, noWrap )###

Get a Make list with the given ID

id - required - ID of the list that is to retrieved
callback - required - A function to pass the result into
noWrap - 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!

);

getListsByUser( userId, callback )###

Get a Users lists

userId - required - ID of the user whose lists are to be retrieved
callback - required - A function to pass the result into