Into The Box Notes: GET /cfml - Matthew Clemente
list of APIs available
we use APIs so we don’t have to reinvent the wheel
1st step - don’t write the api wrapper, look at the repos to see if 1 already exists. someone may have already done the work for you.
ALL API’s are about the same
requests and responses are all about the same
Book: “Rest Assured” by Adam Tuttle
method - get, put, post, etc
url - a constant: “site.com/thing”
where content type and authentication takes place
headers are important - say if you’re sending json or if json is coming back
set this 1 time, then they are the same on every request
only need to get the value once for the entire wrapper cfc
most of your work is dealing with the URL params and the body.
make sure these URL vars get sent to the API
status code and text
was it successful or not?
header might have additional info that’s helpful
data is your actual data response
box install api-wrapper-template
module for scaffolding wrapper for APIs
includes methods for building the body, concatenating query strings, etc.
an API doesn’t exist unless it’s being used
getting started -
authentication / authorization
endpoint / test endpoint
other limitations, etc
look at other API clients and client libraries
if docs are confusing, the code in the other libraries will show you how it’s done
they may have clever solutions to thinks you didn’t think of, etc.
doesn’t matter if it’s PHP or Node, etc.
you can read the code even if you don’t write that language
The Cat API
“apiWrapper scaffold —wizard”
When you’re writing an API, you’re audience is developers
be consistent when naming your resources
easier for yourself and people using your wrapper
“get”Thing() when providing an ID
“list”Thing() when not providing an ID for a specific entry
want to make your life easier when writing a wrapper
every arg passed in, set as a variable
most API’s have authentication
basic username:password in an authorization header
API Key Auth - you get an API key and they ask you to give it back to them somehow (maybe in a header, maybe somewhere else)
Open Authorization (OAuth, OAuth2) - when a 3rd party is involved saying “okay the wrapper can access my data from the API provider”
how to do it in CF —
for user/pass, use cfhttp username and password attributes
API key - use CFHttpParam type = “header”
getBaseHttpHeaders() in the api-wrapper-template module
- if you need to pass headers, just use that method and it will be taken care of
handled automatically in the api-wrapper-template
Should we validate the parameters?
what if the input was empty? is the url.foo a valid value?
Don’t reinvent the wheel
Don’t validate the params coming into the API wrapper
the API itself does validation and returns error messages
just get that info and pass it back to your users
document your api wrappers!
developers are your audience
you want to put effort into this
document the methods as you go so it doesn’t become an overwhelming burden
blog article: rowmanning.com “writing a friendly readme”