README.md

GampangHTTP

Dead-simple HTTP Networking in Swift using URLSession.

Table of Contents

• Installation
• Usage
  • Basic Usage
  • Advanced Configuration
• Request Construction
  • Creating a Basic Request
  • Setting HTTP Method
  • Adding Headers
  • Adding Query Items
  • Setting Request Body
  • Combining Multiple Components
  • Using GampangURLRequest with GampangHTTP
• Features
  • Caching
  • Certificate Pinning
  • Retry Policy
  • Logging

Installation

GampangHTTP can be installed using Swift Package Manager. Add it to your project's Package.swift file:

dependencies: [
    .package(url: "https://github.com/mrandika/swift-GampangHTTP.git", from: "x.x.x")
]

Then, add GampangHTTP to your target's dependencies:

targets: [
    .target(
        name: "YourTarget",
        dependencies: ["GampangHTTP"]),
]

Usage

Basic Usage

1. Import GampangHTTP in your Swift file:

import GampangHTTP

2. Create an instance of GampangHTTP:

let http = GampangHTTP()

4. Make a request:

struct HttpBin: Decodable {
    let origin: String
    let url: String
}

do {
    let response: HttpBin = try await http.request(
        with: URLRequest(url: URL(string: "https://httpbin.org/get")!),
        of: HttpBin.self
    )

    print("Response: \(response.origin) \(response.url)")
} catch {
    print("Error: \(error)")
}

Advanced Configuration

You can customize GampangHTTP with various options:

let customHTTP = GampangHTTP(
    cache: URLCache(memoryCapacity: 20_000_000, diskCapacity: 200_000_000, diskPath: "custom_cache"),
    logger: CustomLogger(),
    retryPolicy: CustomRetryPolicy(),
    pinnedCertificates: [/* Your pinned certificates */]
)

Request Construction

GampangHTTP uses GampangURLRequest to construct HTTP requests. This struct provides a convenient way to set various components of a request.

Creating a Basic Request

let request = GampangURLRequest(url: "https://api.example.com/users", method: .get)

Setting HTTP Method

let postRequest = GampangURLRequest(url: "https://api.example.com/users", method: .post)

Available HTTP methods:

1. .post
2. .get
3. .put
4. .delete
5. .patch
6. .head
7. .options
8. .trace
9. .connect

Reference: HTTP request methods

Adding Headers

let request = GampangURLRequest(
    url: "https://api.example.com/users",
    method: .get,
    headers: [
        (.contentType, "application/json"),
        (.authorization, "Bearer your-token-here")
    ]
)

Available header fields:

1. .contentType
2. .authorization
3. .accept

💡 More header fields and custom are coming soon.

Adding Query Items

let request = GampangURLRequest(
    url: "https://api.example.com/search",
    method: .get,
    queryItems: [
        URLQueryItem(name: "q", value: "swift"),
        URLQueryItem(name: "page", value: "1")
    ]
)

Setting Request Body

For requests with a JSON body:

let body: [String: Any] = ["name": "John Doe", "email": "john@example.com"]
let request = GampangURLRequest(
    url: "https://api.example.com/users",
    method: .post,
    body: body
)

For requests with raw data:

Alternatively, you can use Encodable protocol and convert it to data representation

let data = "Raw data".data(using: .utf8)!
let request = GampangURLRequest(
    url: "https://api.example.com/upload",
    method: .post,
    data: data
)

Combining Multiple Components

You can combine all these components in a single request:

let request = GampangURLRequest(
    url: "https://api.example.com/users",
    method: .post,
    body: ["name": "John Doe", "email": "john@example.com"],
    queryItems: [URLQueryItem(name: "version", value: "v2")],
    headers: [
        (.contentType, "application/json"),
        (.authorization, "Bearer your-token-here")
    ]
)

Using GampangURLRequest with GampangHTTP

Once you've constructed your request, you can use it with GampangHTTP:

let http = GampangHTTP()

do {
    let urlRequest = try request.build
    let response: APIResponse = try await http.request(with: urlRequest, of: APIResponse.self)
    print("Response: \(response)")
} catch {
    print("Error: \(error)")
}

Note: The build property of GampangURLRequest converts it to a URLRequest, which can be used with GampangHTTP.

Features

Caching

GampangHTTP supports response caching out of the box. To disable caching:

let httpNoCache = GampangHTTP(cache: nil)

Certificate Pinning

Enable certificate pinning by providing an array of pinned certificates:

let httpWithPinning = GampangHTTP(pinnedCertificates: [/* Your pinned certificates */])

Retry Policy

GampangHTTP uses a default retry policy. You can provide a custom policy:

class CustomRetryPolicy: GampangRetryPolicy {
    // Implement your custom retry logic here
}

let httpWithCustomRetry = GampangHTTP(retryPolicy: CustomRetryPolicy())

Logging

GampangHTTP includes a default console logger. You can provide a custom logger:

class CustomLogger: GampangLogger {
    func log(_ message: String) {
        // Implement your custom logging logic here
    }
}

let httpWithCustomLogger = GampangHTTP(logger: CustomLogger())