Postman is a useful client, but the command line is a quicker, faster way to productively check API calls learning about APIs. This article will show you how to set up your terminal to be able to:
-
Change between ManageBac and OA apis
-
Execute endpoints
-
Add query parameters
- Execute post commands
-
Open the response in Visual Code studio
Please note that these steps are specific to Mac / Unix.
Example
Install HTTPie
brew install httpie
It may be worth understanding how to build a request with httpie, and fundamentally looks like this:
https GET api.managebac.com/school auth-token:secret
But even that's a lot of typing — we'll get it to just the bare essentials.
Create parent directory
We'll store some configuration files in one director to make it easy to switch between schools
mkdir -p ~/path/to/directory
cd ~/path/to/directory
Now let's make our first configuration file. We'll use the school.managebac instance as an example:
nano school.mb
In a new file called "school.mb" , type the following commands (or copy and paste):
export TOKEN=secret
export BASEURL=api.managebac.com/v2
export METHOD=GET
FETCH () {
https --print=b $METHOD $BASEURL/$@ auth-token:$TOKEN
}
Save, and now have a way of declaring variables and their values, for easy switching. When you want to activate the school.managebac api token, just do this:
source school.mb
You have now switched the context to use your school's APis.
Use the command
When you "source" the file, you get the function FETCH which will use httpie to get the Get all Students endpoint:
FETCH students
By having a file for MB and one for OA, you can easily go back and forth.
To change what endpoint, for example use the Year Groups endpoint, simply execute FETCH after reassigning the ENDPOINT variable.
FETCH year-groups
To add a query parameter, such as per_page, execute the command after typing the following:
FETCH students per_page==1
Please note that double equals (==) is required as this is the expected format for httpie.
To change from GET to POST method, and send it a body, do this:
FETCH POST students first_name="Some name"
Automatically open in Visual Code Studio
It might be easier to scroll, copy-and-paste, or take screenshots of the responses by sending it directly to a text editor, such as Visual Code Studio.
You can define a new function that does exactly that, call it FETCH_VS maybe:
FETCH_VS {
METHOD=$1; shift
https --pretty=format --print=b $1 $BASEURL/$@ auth_token:$TOKEN | code -
}
This is essentially changing it so that httpie does not output colors but still outputs formatting whitespace, and pipes it to the command line tool that Visual Code Studio has to automatically open in a new file.
Use for OpenApply
ManageBac is used as a specific example, but the same pattern holds for OpenApply v1:
export TOKEN=SkSxOpfx9eEFJrspcdaw60l4Cjl4_vL897ctj_FoqkQ
export SUBDOMAIN=school
export BASEURL=$SUBDOMAIN.openapply.com/api/v1
export ENDPOINT=students
export METHOD=GET
FETCH () {
METHOD=$1; shift
https --print=b $METHOD $BASEURL/$@ auth_token==$TOKEN
}
However using this technique with v3, which uses oauth2 authentication, some extra work is needed. You essentially have to manually grab the TOKEN by calling OAUTH, paste that token at the top of the file, and then use FETCH.
The source file should be the following:
export TOKEN=secret
export SUBDOMAIN=school
export CLIENT_ID=secret
export CLIENT_SECRET=secret
export BASEURL=$SUBDOMAIN.openapply.com/api/v3
export METHOD=GET
alias OAUTH="https -a $CLIENT_ID:$CLIENT_SECRET POST $SUBDOMAIN.openapply.com/oauth/token grant_type=client_credentials"
FETCH () {
METHOD=$1; shift
https --print=b -A bearer -a $TOKEN $1 $BASEURL/$@
}
To use it, you'll have to get the bearer token with:
OAUTH
And then copy and paste "access_token" to the TOKEN variable at the top of the file, and then:
FETCH