gombta.go

/*
Package gombta is a MBTA v2 client written for the Go programming language

Sep 2015
*/
package gombta

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "os"
)

//Client interacts with the services provided by MBTA
type Client struct {
    APIKey string // private API key
    URL    string // MBTA URL, probably ends with .../v2/. Must end in '/'.
}

//AllRoutes is base return of MBTA All Route Call
//When making MBTA Route Call it returns nested JSON
//This block supports the nesting
type AllRoutes struct {
    Mode []struct {
        RouteType string `json:"route_type"`
        ModeName  string `json:"mode_name"`
        Route     []struct {
            RouteID   string `json:"route_id"`
            RouteName string `json:"route_name"`
        } `json:"route"`
    } `json:"mode"`
}

//
//
// END BLOCK
//
//

// ClientError is a generic error specific to the `gombta` package.
type ClientError struct {
    msg string
}

// Error returns a string representation of the error condition.
func (c ClientError) Error() string {
    return c.msg
}

// UseDefaultURL configures a `Client` to use the default public
//   MBTA URL published on their website.
func (c *Client) UseDefaultURL() {
    c.URL = "http://realtime.mbta.com/developer/api/v2/"
}

// checkApiKey ensures that the user configured her API key,
//   or returns an error.
func (c *Client) checkAPIKey() (err error) {
    if c.APIKey == "" {
        return ClientError{msg: "Empty API key is invalid"}
    }
    return nil
}

// makeAPIGetRequest fetches a URL with querystring via HTTP GET and
//  returns the response if the status code is HTTP 200
// `parameters` should not include the apikey.
// The caller must call `resp.Body.Close()`.
func (c *Client) makeAPIGetRequest(fullurl string, parameters map[string]string) (resp *http.Response, err error) {
    if err = c.checkAPIKey(); err != nil {
        return resp, err
    }

    values := url.Values{}
    values.Set("api_key", c.APIKey)
    for k, v := range parameters {
        values.Add(k, v)
    }

    httpClient := http.Client{}
    // TODO(wb) check if final character is ?, or if ? already exists
    req, err := http.NewRequest("GET", fullurl+"?"+values.Encode(), nil)
    if err != nil {
        return resp, err
    }

    resp, err = httpClient.Do(req)
    if err != nil {
        return resp, err
    }

    if resp.StatusCode != 200 {
        var msg = fmt.Sprintf("Unexpected status code: %d", resp.StatusCode)
        resp.Write(os.Stdout)
        return resp, ClientError{msg: msg}
    }

    return resp, nil
}

//Parameters st
type Parameters map[string]string

// fetchAPIJSON makes a request to the API and decodes the response.
// `method` is one of "GET" -- "POST", or "FILE" are in govt if you need to figure out how to do it
// `actionurl` is the final path component that specifies the API call
// `parameters` does not include the API key
// `result` is modified as an output parameter. It must be a pointer to a MBTA JSON structure.
func (c *Client) fetchAPIJSON(method string, actionurl string, parameters Parameters, result interface{}) (err error) {
    theurl := c.URL + actionurl
    var resp *http.Response
    switch method {
    case "GET":
        resp, err = c.makeAPIGetRequest(theurl, parameters)
    }
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    dec := json.NewDecoder(resp.Body)
    if err = dec.Decode(result); err != nil {
        return err
    }

    return nil
}

// GetRoutes fetches all of the Routes from MBTA
func (c *Client) GetRoutes(format string) (r *AllRoutes, err error) {
    r = &AllRoutes{}
    err = c.fetchAPIJSON("GET", "routes", Parameters{"format": format}, r)
    return r, err
}