<?php
declare(strict_types = 1);

namespace App\Service\Rest;

use App\Service\Rest\Operation\BaseRestOperation;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Symfony\Contracts\HttpClient\ResponseInterface;

/**
 * Interface for services sending requests to an external REST API
 */
interface ApiRequestInterface
{
    /**
     * Sends a GET request and returns the response's body decoded as json
     * @param string $path
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return array<mixed>
     * @throws HttpException
     */
    public function getJsonContent(string $path, array $parameters = [], array $options = []): array;

    /**
     * Sends a GET request and returns the response's body
     *
     * @param string $path
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return string
     * @throws HttpException
     */
    public function getContent(string $path, array $parameters = [], array $options = []): string;

    /**
     * Sends a GET request and returns the response
     *
     * @param string $path
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return ResponseInterface
     * @throws HttpException
     */
    public function get(string $path, array $parameters = [], array $options = []): ResponseInterface;

    /**
     * Sends a POST request and returns the response
     *
     * @param string $path
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return ResponseInterface
     * @throws HttpException
     */
    public function post(string $path, array $parameters = [], array $options = []): ResponseInterface;

    /**
     * Sends a PUT request and returns the response
     *
     * @param string $path
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return ResponseInterface
     * @throws HttpException
     */
    public function put(string $path, array $parameters = [], array $options = []): ResponseInterface;

    /**
     * Sends a DELETE request and returns the response
     *
     * @param string $path
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return ResponseInterface
     * @throws HttpException
     */
    public function delete(string $path, array $parameters = [], array $options = []): ResponseInterface;

    /**
     * Send an HTTP request to a REST API,
     * and return the decoded content of the response's body
     *
     * @param string $method
     * @param string $url
     * @param array<mixed> $parameters
     * @param array<mixed> $options
     * @return ResponseInterface
     * @throws HttpException
     */
    public function request(
        string $method,
        string $url,
        array  $parameters = [],
        array  $options = []
    ): ResponseInterface;
}
