what is the best practice for including ‘wp-includes’ classes

Prerequisites

First, all your callbacks (alias: runtime functions/methods) should be attached to predictable hooks. Example:

add_action( 'plugins_loaded', 'wpse_102852_bootstrap' );
function wpse_102852_bootstrap()
{
    // Time to attach the plugins callbacks
    add_action( 'wp_loaded', 'some_callback' );
}

This callback is attached to the first hook that is available for plugins. Now other plugins know when your plugin is loading and attaching hooks.

You will want to wrap all those tasks you perform into methods in your class and attach them to your bootstrap/constructor method. In there you attach those methods to hooks.

Running HTTP remote requests

The WP HTTP API provides a handy set of public API functions and filters that you can use to do your requests.

First you might want to use one of the following functions depending on what you need:

• wp_remote_get()
• wp_remote_post()
• wp_remote_head()
• wp_remote_request()

The wp_remote_head() function normally is used to just test for availability or support for some required header.

When you’re done with your request you’re able to test and validate if there was an error:

$request = wp_remote_request( array( /* your arguments */ ) );
// Quite handy that wrong responses are return as WP_Error object
if (
    is_wp_error( $request )
    // Most remote APIs send the wrong response codes and tell your everything is fine
    // just to use their own bogus error messages to annoy the shit out of you.
    // So the following two lines are in 90% of all cases senseless.
    OR 200 !== wp_remote_retrieve_response_code( $request )
    OR "OK" !== wp_remote_retrieve_response_message( $request )
    )
{
    // If the remote API has good response codes, you can use above
    // wp_remote_retrieve_response_code( $request ) as well to get for example 3**, 4** and 5** codes
    return printf( '%s: %s',
        $request->get_error_code(),
        wp_strip_all_tags( $response->get_error_message() )
    );
}

Now you got the response. The question remaining is what format it got. Just use the plain PHP functions like json_decode() for JSON responses, simplexml_load_string() or similar for strings, etc.

Finally it’s time to get the actual data.

// The actual content of the response
$content = wp_remote_retrieve_body( $request );
// An array of headers:
$headers = wp_remote_retrieve_headers( $request );
// An single header: the time the remote data was 'last-modified' for example
// This is helpful to check for remote updates in combination with wp_remote_head()
$headers = wp_remote_retrieve_header( $request, 'last-modified' );

The last task to do is – before touching the content and performing test if we got JSON, XML, XLS, CSV, etc. – some preparation. The first thing always is to do a trim(): Nearly every provider stuffs empty spaces around the response by accident.

$content = trim( $content );
$content = array_map( 'esc_attr', $content );
// Now check if we got JSON, XML, etc. and process your data.
// Don't forget to use the `esc_*()` functions on the single elements
// Example:
$title = esc_html( $content['title'] );
// etc.

Full blown example

Now here’s an example that does two things:

1. Do the remote request.

2. Attach the data to a filter that you can use in templates to grab your data.

   add_action( 'plugins_loaded', array( 'WPSE_102852_Flickr', 'init' ) );
   class WPSE_102852_Flickr
   {
       protected static $instance = null;
   
       public static init()
       {
           null === self::$instance AND self::$instance = new self;
           return self::$instance;
       }
   
       public function __construct()
       {
           add_action( 'wp_loaded', array( $this, 'remote_request' );
       }
   
       public function remote_request()
       {
           // All the logic for the remote request goes in here.
           // Finally you want to save the data somewhere.
           foreach ( $results as $result )
                wp_insert_post( /* your data as post data */ );
       }
   }
   

Now your able to do the following in your template:

$remote_posts = new WP_Query( array( /* your args */ ) );
if ( $remote_posts->have_posts() )
{
    while( $remote_posts->have_posts() )
    {
        the_post();

        the_title();
        the_content();
    }
}
wp_reset_query();
unset( $remote_posts );