makeapi-client
v0.5.30
Published
MakeAPI client library
Downloads
19
Keywords
Readme
The Make API client library works in both browser and node.js contexts. It can also be loaded using require.js.
Constructor
###new Make( options )
###
Returns an instance of the client library that interacts with a Make API server.
options
- An object with the following attributes:
apiURL
- required - A valid URL pointing to the Make API serverapiPrefix
- optional - A path to append the API URL, defaults to"/api/20130724/make/"
csrfToken
- optional - An optional CSRF token to send in request headers (browser environments only)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.
####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: {
// secret shared key
key: "00000000-0000-0000-000000000000",
// public key
id: "00000000-0000-0000-000000000000"
}
});
See the MakeAPI README for more info about API keys and Hawk
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 benull
, 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 namenot
- Boolean value that when settrue
, 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 fornot
- Boolean value that when settrue
, 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 stringsexecution
- 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 settrue
, 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 settrue
, 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 onnot
- Boolean value that when settrue
, 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 fornot
- Boolean value that when settrue
, 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 fornot
- Boolean value that when settrue
, 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 fornot
- Boolean value that when settrue
, 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 valuenot
- Boolean value that when settrue
, 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 valuenot
- Boolean value that when settrue
, 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"
####Example####
var makeapi = new Make( optionsObj );
makeapi
.then(function( err, makes ) {
if ( err ) {
// handle error case
}
var appTags = makes[0].appTags();
console.log( appTags );
});
###userTags()
###
Getter - This function returns all user tags on a make. i.e. "[email protected]:favourite"
####Example####
var makeapi = new Make( optionsObj );
makeapi
.then(function( err, makes ) {
if ( err ) {
// handle error case
}
var userTags = makes[0].userTags();
console.log( userTags );
});
###rawTags()
###
Getter - This function returns all raw tags on a make. i.e. "kittens"
####Example####
var makeapi = new Make( optionsObj );
makeapi
.then(function( err, makes ) {
if ( err ) {
// handle error case
}
var rawTags = makes[0].rawTags();
console.log( rawTags );
});
###taggedWithAny( tags )
###
Determine whether this make is tagged with any of the tags passed in
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.
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 makermake
- 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: "[email protected]",
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 IDsuserId
- required The Unique user ID of the webmaker creating the listtitle
- 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.
console.log( list );
}
);
###updateList( id, options, callback )
###
Updates a Make list with the given options
id
- required - ID of the list that is to updated
options
- required - It should have the following attributes
userId
- required - The Unique user ID of the webmaker updating the listmakes
- An Array of Make IDstitle
- 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 updateduserId
- required - The Unique user ID of the webmaker deleting the listcallback
- 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 retrievedcallback
- required - A function to pass the result intonoWrap
- 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 retrievedcallback
- required - 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 );
}
);