package com.atlassian.bitbucket.rest.fragment;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * The context of a REST fragment request.
 *
 * @since 4.7
 */
public interface RestFragmentContext {

    /**
     * Return a property from the request body of the currently executing REST request.
     *
     * @param key the key of the body property
     * @return the value of the body property
     */
    @Nonnull
    Optional<Object> getBodyProperty(@Nonnull String key);

    /**
     * Return the HTTP method of the currently executing REST request.
     *
     * @return the {@code HttpMethod} being used
     */
    @Nonnull
    String getMethod();

    /**
     * Return the first value of a query parameter of the currently executing REST request.
     * <p>
     * If the query parameter might have more than one value, use {@link #getQueryParameters} instead. If this method is
     * used with a multivalued query parameter, the value returned is equal to the first value in the array returned by
     * {@link #getQueryParameters}.
     *
     * @param name the name of the query parameter
     * @return a {@code String} representing the single value of the query parameter
     */
    @Nonnull
    Optional<String> getQueryParameter(@Nonnull String name);

    /**
     * Return the values of a query parameter of the currently executing REST request.
     *
     * @param name the name of the query parameter
     * @return a {@code List} of {@code String Strings} representing the values of the query parameter, which will be
     * empty if the query parameter does not exist
     */
    @Nonnull
    List<String> getQueryParameters(@Nonnull String name);

    /**
     * Return all of the query parameters of the currently executing REST request, and their values.
     *
     * @return a {@code Map} of query parameter names to a {@code List} of query parameter values for each name
     */
    @Nonnull
    Map<String, List<String>> getQueryParameters();
}