diff --git a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestParameters.h b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestParameters.h index b4428ef559..1b8c47b0ff 100644 --- a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestParameters.h +++ b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestParameters.h @@ -12,21 +12,35 @@ namespace HttpRequestor { - /* - ** - ** The Parameters needed to make a HTTP call and then receive the - ** returned JSON in a meaningful place. Examples of use are in the - ** HttpRequestCaller class. - ** - */ - + //! Models the parameters needed to make a HTTP call and then receive the + //! returned JSON in a meaningful place. Examples of use are in the HttpRequestCaller class. class Parameters { public: - // Initializing ctor + // Ctors + + //! @param URI A universal resource indicator representing an endpoint. + //! @param method The HTTP method to use, for example HTTP_GET. + //! @param callback The callback method to receive a HTTP call's response. Parameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Callback& callback); + + //! @param URI A universal resource indicator representing an endpoint. + //! @param method The HTTP method to use, for example HTTP_GET. + //! @param headers A map of header names and values to use. + //! @param callback The callback method to receive a HTTP call's response. Parameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const Callback& callback); - Parameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const AZStd::string& body, const Callback& callback); + + //! @param URI A universal resource indicator representing an endpoint. + //! @param method The HTTP method to use, for example HTTP_POST. + //! @param headers A map of header names and values to use. + //! @param body An data to associate with an HTTP call. + //! @param callback The callback method to receive a HTTP call's response. + Parameters( + const AZStd::string& URI, + Aws::Http::HttpMethod method, + const Headers& headers, + const AZStd::string& body, + const Callback& callback); // Defaults virtual ~Parameters() = default; @@ -36,30 +50,49 @@ namespace HttpRequestor Parameters(Parameters&&) = default; Parameters& operator=(Parameters&&) = default; - //returns the URI in string form as an recipient of the HTTP connection - const Aws::String& GetURI() const { return m_URI; } + //! Get the URI in string form as an recipient of the HTTP connection. + const Aws::String& GetURI() const + { + return m_URI; + } - //returns the method of which the HTTP request will take. GET, POST, DELETE, PUT, or HEAD - Aws::Http::HttpMethod GetMethod() const { return m_method; } + //! Get the HTTP method configured to use for a request. + Aws::Http::HttpMethod GetMethod() const + { + return m_method; + } - //returns the list of extra headers to include in the request - const Headers & GetHeaders() const { return m_headers; } + //! Get the list of extra headers to send as part of a request. + //! @return A map of header-value pairs. + const Headers& GetHeaders() const + { + return m_headers; + } - //returns the stream for the body of the request - const std::shared_ptr & GetBodyStream() const { return m_bodyStream; } + //! Get an input stream that can be used to send the body of a request. + //! @return A string stream representing a request body. + const std::shared_ptr& GetBodyStream() const + { + return m_bodyStream; + } - //returns the function of which to feed back the JSON that the HTTP call resulted in. The function also requires the HTTPResponseCode indicating if the call was successful or failed - const Callback & GetCallback() const { return m_callback; } + //! Get the callback function for processing JSON returned in an HTTP response. + //! Callback functions are responsible for correctly interpreting the HTTP response code, and should communicate any + //! failures. + //! @return The callback function to process endpoint responses with. + const Callback& GetCallback() const + { + return m_callback; + } private: - Aws::String m_URI; - Aws::Http::HttpMethod m_method; - Headers m_headers; - std::shared_ptr m_bodyStream; // required by Aws::Http::HttpRequest - Callback m_callback; + Aws::String m_URI; + Aws::Http::HttpMethod m_method; + Headers m_headers; + std::shared_ptr m_bodyStream; // required by Aws::Http::HttpRequest + Callback m_callback; }; - inline Parameters::Parameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Callback& callback) : m_URI(URI.c_str()) , m_method(method) @@ -75,7 +108,8 @@ namespace HttpRequestor { } - inline Parameters::Parameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const AZStd::string& body, const Callback& callback) + inline Parameters::Parameters( + const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const AZStd::string& body, const Callback& callback) : m_URI(URI.c_str()) , m_method(method) , m_headers(headers) @@ -83,6 +117,5 @@ namespace HttpRequestor , m_callback(callback) { } - } diff --git a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestorBus.h b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestorBus.h index 5ede4109bb..39cad2c720 100644 --- a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestorBus.h +++ b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpRequestorBus.h @@ -5,7 +5,6 @@ * SPDX-License-Identifier: Apache-2.0 OR MIT * */ - #pragma once #include @@ -13,24 +12,70 @@ namespace HttpRequestor { - class HttpRequestorRequests - : public AZ::EBusTraits + //! Defines request APIs for Gem. Supports making HTTP requests. + //! See [HTTP RFC](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html) for expectations around methods, headers, and body. + class HttpRequestorRequests : public AZ::EBusTraits { - public: static const AZ::EBusHandlerPolicy HandlerPolicy = AZ::EBusHandlerPolicy::Single; static const AZ::EBusAddressPolicy AddressPolicy = AZ::EBusAddressPolicy::Single; - // Public functions + //! Make a RESTful call to a HTTP(s) endpoint. Receive the response, via the supplied callback as JSON. + //! @param URI The universal resource indicator representing the endpoint to make the request to. + //! @param method The HTTP method to use, for example HTTP_GET. + //! @param callback The callback method to receive the JSON response object. virtual void AddRequest(const AZStd::string& URI, Aws::Http::HttpMethod method, const Callback& callback) = 0; - virtual void AddRequestWithHeaders(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers & headers, const Callback& callback) = 0; - virtual void AddRequestWithHeadersAndBody(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers & headers, const AZStd::string& body, const Callback& callback) = 0; - + + //! Make a RESTful call to a HTTP(s) endpoint with customized headers. Receive the response, via the supplied callback as JSON. + //! @param URI The universal resource indicator representing the endpoint to make the request to. + //! @param method The HTTP method to use, for example HTTP_GET. + //! @param headers A map of header names and values to set on the request. + //! @param callback The callback method to receive the JSON response object. + virtual void AddRequestWithHeaders( + const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const Callback& callback) = 0; + + //! Make a RESTful call to a HTTP(s) endpoint with customized headers and a body. Receive the response, via the supplied callback as JSON. + //! @param URI The universal resource indicator representing the endpoint to make the request to. + //! @param method The HTTP method to use, for example HTTP_POST. + //! @param headers A map of header names and values to set on the request. + //! @param body Any HTTP request data to include in the request. Use Content-Type and Content-Length headers to specify the nature + //! of the body payload. + //! @param callback The callback method to receive the JSON response object. + virtual void AddRequestWithHeadersAndBody( + const AZStd::string& URI, + Aws::Http::HttpMethod method, + const Headers& headers, + const AZStd::string& body, + const Callback& callback) = 0; + + //! Make a RESTful call to a HTTP(s) endpoint. Receive the response, via the supplied callback as text. + //! @param URI The universal resource indicator representing the endpoint to make the request to. + //! @param method The http method to use, for example HTTP_GET. + //! @param callback The callback method to receive the JSON response object. virtual void AddTextRequest(const AZStd::string& URI, Aws::Http::HttpMethod method, const TextCallback& callback) = 0; - virtual void AddTextRequestWithHeaders(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers & headers, const TextCallback& callback) = 0; - virtual void AddTextRequestWithHeadersAndBody(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers & headers, const AZStd::string& body, const TextCallback& callback) = 0; + + //! Make a RESTful call to a HTTP(s) endpoint with customized headers. Receive the response, via the supplied callback as text. + //! @param URI The universal resource indicator representing the endpoint to make the request to. + //! @param method The HTTP method to use, for example HTTP_GET. + //! @param headers A map of header names and values to set on the request. + //! @param callback The callback method to receive the JSON response object. + virtual void AddTextRequestWithHeaders( + const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const TextCallback& callback) = 0; + + //! Make a RESTful call to a HTTP(s) endpoint with customized headers and a body. Receive the response, via the supplied callback as text. + //! @param URI The universal resource indicator representing the endpoint to make the request to. + //! @param method The HTTP method to use, for example HTTP_POST. + //! @param headers A map of header names and values to set on the request. + //! @param body Any HTTP request data to include in the request. Use Content-Type and Content-Length headers to specify the nature of the body payload. + //! @param callback The callback method to receive the JSON response object. + virtual void AddTextRequestWithHeadersAndBody( + const AZStd::string& URI, + Aws::Http::HttpMethod method, + const Headers& headers, + const AZStd::string& body, + const TextCallback& callback) = 0; }; using HttpRequestorRequestBus = AZ::EBus; -} // namespace HttpRequestor +} // namespace HttpRequestor diff --git a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTextRequestParameters.h b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTextRequestParameters.h index 97c9150f42..0eafdad866 100644 --- a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTextRequestParameters.h +++ b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTextRequestParameters.h @@ -11,20 +11,35 @@ namespace HttpRequestor { - /* - ** - ** The Parameters needed to make a HTTP call and then receive the - ** returned TEXT from the web request without parsing it. - ** - */ - + //! Models the parameters needed to make a HTTP call and then receive the + //! returned TEXT from the web request without parsing it. class TextParameters { public: // Initializing ctor + + //! @param URI A universal resource indicator representing an endpoint. + //! @param method The HTTP method to configure. + //! @param callback The callback method to receive a HTTP call's response. TextParameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const TextCallback& callback); + + //! @param URI A universal resource indicator representing an endpoint. + //! @param method The HTTP method to configure. + //! @param headers A map of header names and values to use. + //! @param callback The callback method to receive a HTTP call's response. TextParameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const TextCallback& callback); - TextParameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const AZStd::string& body, const TextCallback& callback); + + //! @param URI A universal resource indicator representing an endpoint. + //! @param method The HTTP method to configure. + //! @param headers A map of header names and values to use. + //! @param body An data to associate with an HTTP call. + //! @param callback The callback method to receive a HTTP call's response. + TextParameters( + const AZStd::string& URI, + Aws::Http::HttpMethod method, + const Headers& headers, + const AZStd::string& body, + const TextCallback& callback); // Defaults ~TextParameters() = default; @@ -34,29 +49,49 @@ namespace HttpRequestor TextParameters(TextParameters&&) = default; TextParameters& operator=(TextParameters&&) = default; - //returns the URI in string form as an recipient of the HTTP connection - const Aws::String& GetURI() const { return m_URI; } + //! Get the URI in string form as an recipient of the HTTP connection. + const Aws::String& GetURI() const + { + return m_URI; + } - //returns the method of which the HTTP request will take. GET, POST, DELETE, PUT, or HEAD - Aws::Http::HttpMethod GetMethod() const { return m_method; } + //! Get the HTTP method configured to use for a request. + Aws::Http::HttpMethod GetMethod() const + { + return m_method; + } - //returns the list of extra headers to include in the request - const Headers & GetHeaders() const { return m_headers; } + //! Get the list of extra headers to send as part of a request. + //! @return A map of header-value pairs. + const Headers& GetHeaders() const + { + return m_headers; + } - //returns the stream for the body of the request - const std::shared_ptr & GetBodyStream() const { return m_bodyStream; } + //! Get an input stream that can be used to send the body of a request. + //! @return A string stream representing a request body. + const std::shared_ptr& GetBodyStream() const + { + return m_bodyStream; + } - //returns the function of which to feed back the TEXT that the HTTP call resulted in. The function also requires the HTTPResponseCode indicating if the call was successful or failed - const TextCallback & GetCallback() const { return m_callback; } + //! Get the callback function for processing text returned in an HTTP response. + //! Callback functions are responsible for correctly interpreting the HTTP response code, and should communicate any + //! failures. + //! @return The callback function to process endpoint responses with. + const TextCallback& GetCallback() const + { + return m_callback; + } private: - Aws::String m_URI; - Aws::Http::HttpMethod m_method; - Headers m_headers; - std::shared_ptr m_bodyStream; - TextCallback m_callback; + Aws::String m_URI; + Aws::Http::HttpMethod m_method; + Headers m_headers; + std::shared_ptr m_bodyStream; + TextCallback m_callback; }; - + inline TextParameters::TextParameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const TextCallback& callback) : m_URI(URI.c_str()) , m_method(method) @@ -64,7 +99,8 @@ namespace HttpRequestor { } - inline TextParameters::TextParameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const TextCallback& callback) + inline TextParameters::TextParameters( + const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const TextCallback& callback) : m_URI(URI.c_str()) , m_method(method) , m_headers(headers) @@ -72,12 +108,17 @@ namespace HttpRequestor { } - inline TextParameters::TextParameters(const AZStd::string& URI, Aws::Http::HttpMethod method, const Headers& headers, const AZStd::string& body, const TextCallback& callback) + inline TextParameters::TextParameters( + const AZStd::string& URI, + Aws::Http::HttpMethod method, + const Headers& headers, + const AZStd::string& body, + const TextCallback& callback) : m_URI(URI.c_str()) , m_method(method) , m_headers(headers) - , m_bodyStream( std::make_shared(body.c_str()) ) + , m_bodyStream(std::make_shared(body.c_str())) , m_callback(callback) { } -} +} // namespace HttpRequestor diff --git a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTypes.h b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTypes.h index a13f2f5645..42efa169dd 100644 --- a/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTypes.h +++ b/Gems/HttpRequestor/Code/Include/HttpRequestor/HttpTypes.h @@ -23,20 +23,16 @@ AZ_POP_DISABLE_WARNING namespace HttpRequestor { - // - // the call back function for http requests. - // + // A callback function for processing JSON return values from an HTTP request. This callback is responsible for correctly interpreting + // the HTTP response code and setting any internal information from the returned JSON object. using Callback = AZStd::function; - - // - // the call back function for any http text requests. - // + // A callback function for processing HTTP response as raw text. This callback is responsible for correctly interpreting the HTTP + // response code and setting any internal information from the returned data. If the data includes a JSON fragment, the callback is + // responsible for parsing it. using TextCallback = AZStd::function; - - // - // a map of REST headers. - // + // A map of REST headers. using Headers = AZStd::map; -} + +} // namespace HttpRequestor