James Gibson
slides.com/jamesgibson-3/deck/live
Wikipedia defines an API as:
In computer programming, an application programming interface (API) is a set of routines, protocols, and tools for building software applications. An API expresses a software component in terms of its operations, inputs, outputs, and underlying types.
Getting system A to do work for system B
An API can provide:
An API can provide:
You may have the chance to work on really well designed API's, but...
You will more then likely have to work on really bad API's
credit: Dann Stockton & David Stockton
Many common mistakes occur simply due to lack of experience
Every ms that your request takes is time that adds up for the end user.
Not every developer has the same level of restrictions that you do.
Some platforms impose timeout limits that cannot be raised.
Eating up transaction time with requests is a generally easy
problem to fix.
function verifyUserKey(req, res, next) {
var userId = req.query.userId,
key = req.query.key,
token = authModel.getToken(userId,key);
if(!token) { return res.json({message:"Invalid User and Key"}); }
req.token = token;
next();
}
function verifyUserKey(req, res, next) {
//Fail before making database calls
var userId = req.query.userId,
key = req.query.key;
if (typeof userId === "undefined" || typeof key === "undefined") {
return invalidCredentials();
}
req.token = authModel.getToken(userId,key);
if(!req.token) {return invalidCredentials();}
next();
function invalidCredentials() {
res.json({message:"Invalid User and Key"});
}
}
Validate inputs early
function verifyUserKey(req, res, next) {
var userId = req.query.userId,
key = req.query.key;
if (typeof userId === "undefined" || typeof key === "undefined") {
return invalidCredentials();
}
req.token = authModel.getToken(userId,key);
if(!req.token) {return invalidCredentials();}
next();
function invalidCredentials() {
//Fail with status
res.status(401)
.json({message:"Invalid User and Key"});
}
}
Returning `200 OK` for every request masks issues.
HTTP Status Codes Exist! Use them!
function verifyUserKey(req, res, next) {
var userId = req.query.userId,
key = req.query.key;
if (typeof userId === "undefined" || typeof key === "undefined") {
return invalidCredentials();
}
req.token = authModel.getToken(userId,key);
if(!req.token) {return invalidCredentials();}
next();
function invalidCredentials() {
//Fail with status, message, and a code
res.status(401)
.json({
message:"Invalid User and Key"
,code:"401"
});
}
}
Some consumers actually won't have access to the underlying response status code
while this is not required, it can make integrating with your API easier.
Flash was a good example of this, the browsers would catch failed requests and not allow the runtime access to the underlying error.
Operate under the principle of least surprise
Developers that use your API are almost always on a time crunch. Respect their time.
Make learning your API a no brainer by providing working examples, good documentation and consistent assumptions.
credit: http://www.jaas.co && @jasper9
Postman
Strive to produce mature API's
Twitter: @brainchildpro
Denver Devs Slack: james.the.nodester