top
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!
});
});
|