package io;

import java.io.IOException;
import org.json.JSONObject;

/**
 * Performs an API request.
 *
 * @author Peter Wu
 */
public interface Requester {

    /**
     * Performs an API request for a resource, for example
     * "statuses/mentions_timeline" (note, no leading slash nor ".json" suffix).
     * Prefix the resource with "1/" when you really need to target the old 1.0
     * API.
     *
     * @param resource The REST resource.
     * @return A JSON object resulting from the request.
     * @throws java.io.IOException on error fetching the resource.
     */
    public JSONObject getJSON(String resource) throws IOException;

    /**
     * Almost equivalent to {@code getJSON(resource, true)}, except that an
     * IOException is not thrown if the request reports an non-successful status
     * code.
     *
     * @see Requester#getJSON(java.lang.String, boolean)
     * @throws IOException on network errors or if the response could not be
     * parsed into a valid JSONObject.
     */
    public JSONObject getJSONRelax(String resource) throws IOException;

    /**
     * Tests whether this instance can dispatch requests.
     *
     * @return true if the access tokens are valid, false otherwise.
     * @throws java.io.IOException if the status cannot reliably be determined
     * (e.g. network error, parsing error).
     */
    public boolean isValid() throws IOException;
}