Into The Box Notes: GET /cfml - Matthew Clemente

April 29, 2018

github.com/toddmotto/public-apis
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”

headers
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

response -
status code and text
was it successful or not?
header might have additional info that’s helpful
data is your actual data response

api-wrapper-template
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
rate limits
response format
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

init()
every arg passed in, set as a variable

Authentication —
most API’s have authentication

3 types
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

Environment variables
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”