travel.izi.api.service.FeaturedService Maven / Gradle / Ivy

Go to download
/*
 * Copyright (C) 2014 IZITEQ B.V.
 *
 * 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 travel.izi.api.service;

import retrofit2.Call;
import retrofit2.http.GET;
import retrofit2.http.Query;
import travel.izi.api.model.entity.AppFeaturedObject;
import travel.izi.api.model.entity.WebFeaturedObject;

import java.util.List;

/**
 * Endpoints for Featured Content.
 */
@SuppressWarnings("unused")
public interface FeaturedService {

    /**
     * Provides current featured content for izi.TRAVEL Applications (mobile clients):
     * promoted or most popular published tours and museums.
     * 
     * The end-point returns only published content in order defined by a featured content publisher
     * (position field reflects the ordering as well). The maximum number of returned objects is 10.
     * 

     * If there is no set defined for the first language or there is no published content for the
     * language, the end-point will try to return featured content set for next language, and so
     * forth.
     * If there are no featured content for the set of passed languages, the end-point will try
     * to return set for `en` language.
     * 
     *
     * @param languages Array of preferable content languages.
     * @return Featured content or throw HTTP error 404 if no appropriate featured content are
     * published.
     */
    @GET("/featured/mobile")
    Call> appFeaturedContent(
            @Query("languages") String[] languages
    );

    /**
     * The endpoint provides current featured content: promoted or most popular tours, museums
     * and cities. This is a special endpoint mostly used on izi.TRAVEL site.
     * 
     * The end-point returns the following sets of objects for a requested language:
     * 
     * 
     * 
     * A primary set of museums and tours indicating position of a content in izi.TRAVEL dashboard
     * (see position field in response). The position value can be [1..5], however, the primary set
     * does not always keep content for all position values.
     * 
     * 
     * A secondary set of museums and tours where the position is not provided. The secondary set
     * is used for cases when a dashboard has more than 5 places or when the primary set does not
     * have content with certain position value.
     * 
     * 
     * A set of cities (without position) used for showing a city in a dashboard. The showing of
     * cities can be in random order, for example, in time-based or refresh-based manner in some
     * place of a dashboard.
     * 
     * 
     *
     * @param languages Array of preferable content languages.
     * @return Featured content or throw HTTP error 404 if no appropriate featured content are
     * published.
     */
    @GET("/featured")
    Call> webFeaturedContent(
            @Query("languages") String[] languages
    );

}