twitter4j.v1.HelpResources Maven / Gradle / Ivy

/*
 * Copyright 2007 Yusuke Yamamoto
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package twitter4j.v1;

import twitter4j.TwitterException;

import java.io.Serializable;
import java.util.Map;

/**
 * @author Joern Huxhorn - jhuxhorn at googlemail.com
 */
public interface HelpResources {

    /**
     * Returns the list of languages supported by Twitter along with their ISO 639-1 code. The ISO 639-1 code is the two letter value to use if you include lang with any of your requests.
     *
     * @return list of languages supported by Twitter
     * @throws twitter4j.TwitterException when Twitter service or network is unavailable
     * @see GET help/languages | Twitter Developers
     * @since Twitter4J 2.2.3
     */
    ResponseList getLanguages() throws TwitterException;

    /**
     * represents language
     */
    interface Language extends Serializable {
        /**
         * @return language name
         */
        String getName();

        /**
         * @return language code
         */
        String getCode();

        /**
         * @return status
         */
        String getStatus();
    }

    /**
     * Returns the current rate limits for methods belonging to the specified resource families.

     * Each 1.1 API resource belongs to a "resource family" which is indicated in its method documentation. You can typically determine a method's resource family from the first component of the path after the resource version.

     * This method responds with a map of methods belonging to the families specified by the resources parameter, the current remaining uses for each of those resources within the current rate limiting window, and its expiration time in epoch time. It also includes a rate_limit_context field that indicates the current access token context.

     * You may also issue requests to this method without any parameters to receive a map of all rate limited GET methods. If your application only uses a few of methods, please explicitly provide a resources parameter with the specified resource families you work with.

     * Read more about REST API Rate Limiting in v1.1 and review the limits.

     * 
This method calls https://api.twitter.com/1.1/application/rate_limit_status.json
     *
     * @return the rate limit statuses
     * @throws TwitterException when Twitter service or network is unavailable
     * @see GET application/rate_limit_status
     * @since Twitter4J 3.0.0
     */
    Map getRateLimitStatus() throws TwitterException;

    /**
     * Returns the current rate limits for methods belonging to the specified resource families.

     * Each 1.1 API resource belongs to a "resource family" which is indicated in its method documentation. You can typically determine a method's resource family from the first component of the path after the resource version.

     * This method responds with a map of methods belonging to the families specified by the resources parameter, the current remaining uses for each of those resources within the current rate limiting window, and its expiration time in epoch time. It also includes a rate_limit_context field that indicates the current access token context.

     * You may also issue requests to this method without any parameters to receive a map of all rate limited GET methods. If your application only uses a few of methods, please explicitly provide a resources parameter with the specified resource families you work with.

     * Read more about REST API Rate Limiting in v1.1 and review the limits.

     * As of Nov 4th 2012, supported resource names are as follows:
     * "trends","application","users","saved_searches","geo","direct_messages","blocks","favorites","statuses","followers","help","friends","search","friendships","account","lists"
     * 
This method calls https://api.twitter.com/1.1/application/rate_limit_status.json
     *
     * @param resources resources
     * @return the rate limit statuses
     * @throws TwitterException when Twitter service or network is unavailable
     * @see GET application/rate_limit_status
     * @since Twitter4J 3.0.0
     */
    Map getRateLimitStatus(String... resources) throws TwitterException;
}