Class: DocsKit::ApiRequest

Inherits:
Data
  • Object
show all
Defined in:
lib/docs_kit/api_request.rb

Overview

A single API request, declared once and handed to every client template so a snippet is authored one place, not per language. DocsUI::RequestExample builds one from its args (merging DocsKit.configuration.api_base_url + the auth header) and each DocsKit::ApiClient#template receives it.

req = DocsKit::ApiRequest.new(
method: :post, path: "/v1/things",
url: "https://api.example.com/v1/things",
body: { name: "Acme" }
)
req.http_method       # => "POST"
req.pretty_body_json  # => %({\n  "name": "Acme"\n})

Templates stay one short heredoc each: they read #http_method, #url, #url_with_query, #headers, #body?, and #pretty_body_json.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method:, path:, url:, query: {}, headers: {}, body: nil) ⇒ ApiRequest

Returns a new instance of ApiRequest.



23
24
25
 
# File 'lib/docs_kit/api_request.rb', line 23

def initialize(method:, path:, url:, query: {}, headers: {}, body: nil)
  super
end

Instance Attribute Details

#body ⇒ Object (readonly)

Returns the value of attribute body

Returns:

  • (Object) —

    the current value of body



22
23
24
 
# File 'lib/docs_kit/api_request.rb', line 22

def body
  @body
end

#headers ⇒ Object (readonly)

Returns the value of attribute headers

Returns:

  • (Object) —

    the current value of headers



22
23
24
 
# File 'lib/docs_kit/api_request.rb', line 22

def headers
  @headers
end

#method ⇒ Object (readonly)

Returns the value of attribute method

Returns:

  • (Object) —

    the current value of method



22
23
24
 
# File 'lib/docs_kit/api_request.rb', line 22

def method
  @method
end

#path ⇒ Object (readonly)

Returns the value of attribute path

Returns:

  • (Object) —

    the current value of path



22
23
24
 
# File 'lib/docs_kit/api_request.rb', line 22

def path
  @path
end

#query ⇒ Object (readonly)

Returns the value of attribute query

Returns:

  • (Object) —

    the current value of query



22
23
24
 
# File 'lib/docs_kit/api_request.rb', line 22

def query
  @query
end

#url ⇒ Object (readonly)

Returns the value of attribute url

Returns:

  • (Object) —

    the current value of url



22
23
24
 
# File 'lib/docs_kit/api_request.rb', line 22

def url
  @url
end

Instance Method Details

#body? ⇒ Boolean

Whether the request carries a payload body (drives whether a template emits its payload lines at all).

Returns:

  • (Boolean) 


32
 
# File 'lib/docs_kit/api_request.rb', line 32

def body? = !body.nil?

#http_method ⇒ Object

The upcased HTTP verb for display in a snippet ("POST", "GET", ...).



28
 
# File 'lib/docs_kit/api_request.rb', line 28

def http_method = method.to_s.upcase

#pretty_body_json ⇒ Object

The body as pretty-printed JSON with string keys (deep-stringified), or nil when there is no body. A String body is passed through unchanged.



36
37
38
39
40
41
 
# File 'lib/docs_kit/api_request.rb', line 36

def pretty_body_json
  return nil unless body?
  return body if body.is_a?(String)

  JSON.pretty_generate(deep_stringify(body))
end

#query_string ⇒ Object

A URL-encoded "?a=1&b=2" query string, or "" when there is no query.



44
45
46
47
48
 
# File 'lib/docs_kit/api_request.rb', line 44

def query_string
  return "" if query.nil? || query.empty?

  "?#{URI.encode_www_form(query)}"
end

#url_with_query ⇒ Object

The URL with the query string appended (the copy-pasteable request target).



51
 
# File 'lib/docs_kit/api_request.rb', line 51

def url_with_query = "#{url}#{query_string}"