Humaans.Client (Humaans v0.4.0)

View Source

Internal module for making HTTP requests to the Humaans API.

This module provides a consistent interface for all HTTP operations used by the resource modules. It handles:

  • Constructing proper URLs
  • Setting up appropriate headers
  • Selecting the right HTTP method
  • Processing request parameters
  • Delegating to the configured HTTP client

Architecture

The client module sits between resource modules (like Humaans.People) and the actual HTTP client implementation (like Humaans.HTTPClient.Req):

Resource Modules (People, Companies, etc.)
       
       
  Humaans.Client
       
       
HTTP Client Implementation

This layered approach allows:

  1. Resource modules to focus on their specific API operations
  2. HTTP client implementations to focus on HTTP communication details
  3. This module to provide a consistent interface between them

Internal Use

This module is primarily meant for internal use by other modules in the library. End users should interact with the resource modules instead.

Summary

Types

Standard response format from HTTP operations.

Functions

Makes a DELETE request to the specified path.

Makes a GET request to the specified path.

Makes a GET request with query parameters.

Makes a PATCH request to update an existing resource.

Makes a POST request to create a new resource.

Types

response()

@type response() :: {:ok, map()} | {:error, map()}

Standard response format from HTTP operations.

  • {:ok, map()} - Successful response with decoded response body
  • {:error, map()} - Error response with error details

Functions

delete(client, path)

@spec delete(client :: map(), path :: String.t()) :: response()

Makes a DELETE request to the specified path.

Used for deleting resources from the Humaans API.

Parameters

  • client - The Humaans client struct
  • path - API endpoint path (e.g., "/people/123")

Returns

  • {:ok, response} - Successful deletion response
  • {:error, reason} - Error response

get(client, path)

@spec get(client :: map(), path :: String.t()) :: response()

Makes a GET request to the specified path.

Used for retrieving resources from the Humaans API.

Parameters

  • client - The Humaans client struct
  • path - API endpoint path (e.g., "/people/123")

Returns

  • {:ok, response} - Successful response with retrieved data
  • {:error, reason} - Error response

get(client, path, params)

@spec get(client :: map(), path :: String.t(), params :: keyword()) :: response()

Makes a GET request with query parameters.

Used for retrieving resources with filtering, pagination, or other query parameters.

Parameters

  • client - The Humaans client struct
  • path - API endpoint path (e.g., "/people")
  • params - Query parameters as keyword list (e.g., [limit: 10, skip: 20])

Returns

  • {:ok, response} - Successful response with retrieved data
  • {:error, reason} - Error response

patch(client, path, params \\ [])

@spec patch(client :: map(), path :: String.t(), params :: keyword()) :: response()

Makes a PATCH request to update an existing resource.

Used for updating resources in the Humaans API.

Parameters

  • client - The Humaans client struct
  • path - API endpoint path (e.g., "/people/123")
  • params - Request body parameters with fields to update (optional, defaults to empty list)

Returns

  • {:ok, response} - Successful response with updated resource data
  • {:error, reason} - Error response

post(client, path, params \\ [])

@spec post(client :: map(), path :: String.t(), params :: keyword()) :: response()

Makes a POST request to create a new resource.

Used for creating new resources in the Humaans API.

Parameters

  • client - The Humaans client struct
  • path - API endpoint path (e.g., "/people")
  • params - Request body parameters (optional, defaults to empty list)

Returns

  • {:ok, response} - Successful response with created resource data
  • {:error, reason} - Error response