package com.atlassian.bitbucket.rest.fragment;

import javax.annotation.Nonnull;
import java.util.Map;

/**
 * Allows the injection of REST handling into existing REST endpoints provided by the host application.
 *
 * @see RestFragments
 * @since 4.7
 */
public interface RestFragment {

    /**
     * Execute the REST fragment.
     *
     * @param fragmentContext the context for the REST fragment, including the HTTP method, the body, and any query
     *                        parameters
     * @param requestContext any properties provided by the request (such as the project, repository, or pull request,
     *                       if relevant)
     * @return a Map representation of the REST response
     */
    @Nonnull
    Map<String, Object> execute(@Nonnull RestFragmentContext fragmentContext, @Nonnull Map<String, Object> requestContext);

    /**
     * Validate the body of the REST fragment request. This method <em>should not</em> persist any changes in the
     * application, as validation may fail on another fragment not specified by this {@link RestFragment}.
     *
     * See {@link #execute}, which is invoked after this method if all fragments have successfully validated. This
     * method should make all reasonable attempts to ensure that the subsequent invocation of {@link #execute} will not
     * fail.
     *
     * @param fragmentContext the context for the REST fragment, including the HTTP method, the body, and any query
     *                        parameters
     * @param requestContext any properties provided by the request (such as the project, repository, or pull request,
     *                       if relevant)
     * @return a Map representation of the validation errors, which will be empty if there are no errors
     */
    @Nonnull
    Map<String, Object> validate(@Nonnull RestFragmentContext fragmentContext, @Nonnull Map<String, Object> requestContext);
}