Making direct api calls

Making direct API calls

Instead of forcing you into using the provided classes to access the Meetup API functionality, this client package actually allows developers to interact directly with the Meetup API using the MeetupApiRequest and MeetupApiResponse objects. This has the added benefit of allowing developers to take advantage of new API features immediately instead of waiting until this client is updated.

Open Source advertisement: This client has been released as an Open Source project. If you add additional functionality to it please submit that functionality back to the project so the community can benefit from it.

Verifying parameters

Each Meetup API endpoint has a specific parameter requirements that must be met in order for the query to execute successfully. There may be several required parameters, however the default behavior of the API is "any of". That means that though five parameters may be required only one of the must exist in any given query. That behavior is important to note as the client emulates this behavior in the MeetupApiRequest::verifyParameters() method.

For this example let's use the events endpoint at /2/events. This endpoint will take in several parameters and attempt to find events that match the given parameters. The following parameters are required (remember, "any of"):

• event_id
• group_id
• group_urlname
• member_id
• venue_id

If you want to find all the events by a specific group you can use the group_urlname or the group_id. In this case use the group_id 1708069. The id corresponds to the Seattle WordPress group. The code will be setup similar to the following:

Make sure a MeetupApiRequest object is available $m = new MeetupApiRequest;

Setup a list of required parameters $required_params = array( 'event_id', 'group_id', 'group_urlname', 'member_id', 'venue_id' );

Create the parameters to send $parameters = array ( 'group_id' => '1708069' );

Verify the parameters are correct $correct_params = $m->verifyParameters( $required_params, $parameters );

verifyParameters() will return a boolean that the calling function can check.

Build the Meetup API URL

The MeetupApiRequest::buildUrl() method not only allows developers to easily build the URL for the query without needing to know any URLs, it also verifies that all the required parameters exist for the API query and throws a MeetupInvalidParametersException if a required parameter is not found. If you want to build a query it is safe to disregard calling MeetupApiRequest::verifyParameters() and use this method only instead.

It is important to note that the Meetup.php file contains several constants that make it so developers do not need to remember the addresses of any endpoint implemented as a helper class. It also contains constants specific to the Meetup API connection such as the API URL and authenticaiton keys. Though you can recreate those constants if you want, it is advisable to simply include the Meetup.php file in your project and strip out any includes you do not want.

The code to build the URL to retrieve the events as above will be similar to the following:

Make sure the MeetupApiRequest object is available $m = new MeetupApiRequest();

Setup the required constants define( 'MEETUP_API_URL', 'https://api.meetup.com' ); define( 'MEETUP_API_KEY', );

Setup a list of required parameters $required_params = array( 'event_id', 'group_id', 'group_urlname', 'member_id', 'venue_id' );

Create the parameters to send $parameters = array ( 'group_id' => '1708069' );

Build the URL $url = $m->buildUrl( '/2/events', $parameters, $required_params );

The call to MeetupApiRequest::buildUrl() will return a URL similar to: https://api.meetup.com/2/events?key=&groupd_id=1708069

Note: This method throws a MeetupInvalidParametersException if there are invalid parameters.

Call to the Meetup API with GET

Making a call with MeetupApiRequest::get() will call the Meetup API directly and bypasses the need to use any of the helper classes. This is particularly useful when adding new functionality or querying an endpoint that does not have a helper class associated with it. To make a call with this method you simply provide the full Meetup API URL as a parameter and after the call runs a MeetupApiResponse object will be returned containing the results of the call.

Carrying on the examples above, the following code shows how to make a call to the events endpoint:

Make sure the MeetupApiRequest object is available $m = new MeetupApiRequest();

Setup the required constants define( 'MEETUP_API_URL', 'https://api.meetup.com' ); define( 'MEETUP_API_KEY', );

Setup a list of required parameters $required_params = array( 'event_id', 'group_id', 'group_urlname', 'member_id', 'venue_id' );

Create the parameters to send $parameters = array ( 'group_id' => '1708069' );

Build the URL to query against $url = $m->buildUrl( '/2/events', $parameters, $required_params );

Call to the Meetup API $response = $m->get( $url );

Note: This method may throw any of the following exceptions to be handled in your application:

• MeetupInvalidParametersException
• MeetupBadRequestException - HTTP 400
• MeetupUnauthorizedRequestException - HTTP 401
• MeetupInternalServerErrorException - HTTP 500

Using the MeetupApiResponse

There are three very simple methods of using the response from the Meetup API query. The MeetupApiRequest object returns the results in a MeetupApiResponse object. These results may be accessed three ways:

• As an array
• As an iterator
• As an array dump of the entire result

As an array

The MeetupApiResponse class implements the PHP ArrayAccess object which allows the developer to use the object result reference as an array instead of as an object similar to the following.

echo $response['0']['name'];

As an iterator

The MeetupApiResponse class also implements the PHP Iterator object which allows the developer to use the result in a loop similar to:

foreach($response as $event) {
    echo $event['name'] . " at " . date(DATE_W3C, $event['time']/1000) . "<br>";
}

As an array dump of the entire result

The final method allows developers to retrieve the entire, unprocessed, API response (Note: It is processed only into into an array). This client actually uses this method rather heavily, though the decision on which method to use in your own applicaiton depends heavily on the needs of the application. You can retrieve the array dump with the following code:

$array = $response->getResponse();