Exploring an API with Fiddler
How many of us can say we didn’t stumble for a little while when learning to ride a bike? Unless you are Travis Pastrana, you probably know what I mean. When it comes to new APIs sometimes we need training wheels too. A good set of training wheels to start getting your feet wet is a “web debugging proxy” or a REST Client.
When calling an API we use HTTP Methods (commonly called “Verbs”). These are defined in the HTTP RFC and allow for several actions to be executed against a URL (or resource). These actions are executed in the form of requests and the server returns what is called a response. When working with an API we need to call it in a specific format. This format is similar to a letter where we have the recipient (header) and the message (or body) of the letter; both the request and response have such fields.
Each API has its own set of required and optional fields that need to be sent in the header and body sections of a request:
1) Verb – This specifies the type of action to be executed. Some of the available verbs are GET, POST, PUT, DELETE, PATCH, etc.—these indicate the intent of the call. If we wanted to retrieve information we would most likely use a GET request. For inserts/updates POST/PUT/PATCH are used (this varies depending on API). And DELETE… well, you can guess that one.
2) URL (Host/Path) – the server to which we will be submitting the call.
3) Headers – These define additional parameters regarding the communication between the server and the client. For example, the type of authentication (or encoding) to be used.
4) Body – This is commonly called the payload. It includes additional parameters to be sent to the server, and in the context of a response, the actual data that was requested.
Here is where Fiddler and other REST clients shine: They allow developers to test and debug an API with ease.
Let’s use our SMS API as an example and check out some of these tools. First we will need some information from the My Apps section at developer.att.com.
You can either create a new app or edit one you previously created.
Copy the App Key, Secret, and Short Code and keep them handy.
First we need to get an OAuth token in order to make subsequent calls to the API. This token allows to identify our app and ensure it is authorized to use the API. Download Fiddler and navigate to the Composer tab. Here we will compose a request with the following parameters:
- Host: api.att.com
- Content-Type: application/json
Where client_id is your App Key and client_secret is your Secret Key.
Note: Make sure Fiddler is capturing traffic, otherwise you won’t be able to see the response from the server. You can ignore additional requests, although it’s entertaining to see all the traffic from your computer sometimes.
Click “Execute” and observe a new request on the left side panel. If we click on that last request, we will see the response from the server, navigate to the Inspectors tab, and scroll down to see the response data.
You should see an access token returned; this will allow your app, website, desktop client, etc. to call our API in an authenticated fashion. A refresh token will also be returned but we won’t use it in this exercise.
Now let’s try sending a text message using our SMS API and access token. The steps are very similar, Replace thexxxxxxxxxxxxxxxxxxxxxxx with youraccess token(from the previous response), the string5555555555with your phone number and the URL withhttps://api.att.com/sms/v3/messaging/outbox. Click “execute” and examine the response for a 201 Result code, which indicates the message was received and sent.
You should see a text message like this right after the 201 response from the server.
Now that you are all set up, feel free to try this today with our APIs.