Don’t Be Scared of API’s!
Don’t Be Scared of API’s! A Beginner’s Guide to API’s Using Meetup and Rails. Part 2: Error Handling and Query Parameters
This blog post is a continuation of Getting Event Data from Meetup’s API Using Ruby on Rails. Here is our checklist of steps required to have a complete solution.
- Get event data from Meetup’s API (Complete!)
- Check for a good connection to Meetup’s API and error handle as necessary
- Use query parameters to refine the data
Step 2: Check for a good connection to Meetup’s API and error handle as necessary.
When connecting to a third party service (such as Meetup’s API) it is important to check for a good response from the server and display an intelligent error to your user. We’re going to update our meetup.rb class to check for a successful connection to the API, and raise a descriptive error if the connection is bad.
Update meetup.rb as shown below:
The general setup andget_data method are from the first tutorial. The events method has changed — what is this new code doing? First, it calls the get_data method. This method uses the HTTParty provided .get method in the line self.class.get(‘/operation-code-hampton-roads/events’). This returns a response that has a parameter .code which represents the HTTP status code sent back from the API. You can see the HTTParty documentation for more information on exactly what is returned if you’re feeling ambitious.
How do we know what .code corresponds to a good connection? Well, we could take an educated guess and we’d probably be correct. But for added peace of mind let’s check the documentation!
Click here to see the Meetup API documentation. Scroll about halfway down the page to the Error heading. I’ve copied the text below and added highlighting.
Awesome! This documentation confirms what we already suspected — a code of 200 means a good response. If you refer back to the events method you’ll see the following if statement:
if get_data.code.to_i == 200
raise "Error fetching data from Meetup API"
If the code is good, return get_data.parsed_response. Remember, .parsed_response is what you use with HTTParty to get the body data. Else, raise an error.
Let’s go to the controller next and rescue this error.
Great work! You’ve now added API error handling to your repertoire of skills.
Let’s review our checklist and see what adventure awaits.
- Get event data from Meetup’s API (Completed!)
- Check for a good connection to Meetup’s API and error handle as necessary (Completed!)
- Use query parameters to refine the data
Step 3: Use query parameters to refine the data
If you’re implementing a Meetup solution for a client, you are going to need to use query parameters. Query parameters are how you tell Meetup specifically what data you want to return. At a minimum, clients will have a private API key (P.S., you have one too!).
Let’s take our existing GET request and add some query parameters in the browser so you can see how they work. Try typing the following in your browser (note: I switched groups to showcase a group with more meetings). I use both Safari and Chrome. Chrome has a nice json viewer which makes understanding your output a little bit easier:
Now, change the URL to:
Did you notice the difference? By changing the page query parameter we changed the number of meetings returned. Cool!
How do you know what query parameters are available? Well, you must refer to the documentation. I know documentation is scary, but it gets easier every time! Click here to see a list of all the available request parameters. You will also see the response parameters, which tells us what data Meetup will return.
One more thing. When implementing this solution in production, you will need an API key to sign the requests. This will be provided by your client (or you can get your own at https://secure.meetup.com/meetup_api/key/). Okay, let’s do this!
In meetup.rb add an options variable, and the initialize method.
You also need to update the get_data method to add the options variable:
What just happened? HTTParty provides a friendly way for you to add query parameters to your request. You create an options variable which we did with attr_reader. Here is a nice review on getters and setters if needed. In the initialize method we set all the query parameters. We can then include @options in our HTTParty get method and the request is created for us. Remember to replace YOUR_API_KEY with your personal API key retrieved from meetup.com. It’s a string, so put it in quotes.
Here is the final version of meetup_controller.rb
And the final meetup.rb
That’s it! You did it!
Hopefully this tutorial gave you a little insight on how to work with API’s and demystified the documentation. API’s are challenging, but once you understand the request and response parameters and how to read the documentation, you’ll be a rockstar!
Some gotchas when working with Meetup’s API:
- If a field doesn’t exist, Meetup does not return that field. This caused me a lot of frustration because I was parsing the JSON returned by field and assumed ‘zip’ would always have a value. If the meeting organizer did not enter a location, there was no zip, and my program crashed. Test for presence of fields before working with the data.
- Time is returned as “UTC start time of the event, in milliseconds since the epoch” Before I provide the time to the front end I convert it:
start_time = Time.at(event[‘time’] / 1000).to_datetime
- End time is not specified, so you need to calculate it using start_time and event_duration.
- Pay close attention to the structure of the JSON data returned if you want to do any additional data processing before serving to the front end. Address is nested under venue: address1: event[‘venue’][‘address_1’], NOT address1: event[‘address_1’]