README.md

RealHTTP is a lightweight yet powerful async-based HTTP library made in Swift.
This project aims to make an easy-to-use, effortless HTTP client based on all the best new Swift features.

What will you get?

Below is a simple HTTP call in RealHTTP.

let todo = try await HTTPRequest("https://jsonplaceholder.typicode.com/todos/1")
           .fetch(Todo.self)

One line of code, including the automatic decode from JSON to object.

Of course, you can fully configure the request with many other parameters. Take a look here:

let req = HTTPRequest {
  // Setup default params
  $0.url = URL(string: "https://.../login")!
  $0.method = .post
  $0.timeout = 15

  // Setup some additional settings
  $0.redirectMode = redirect
  $0.maxRetries = 4
  $0.headers = HTTPHeaders([
    .init(name: .userAgent, value: myAgent),
    .init(name: "X-API-Experimental", value: "true")
  ])
   
  // Setup URL query params & body
  $0.addQueryParameter(name: "full", value: "1")
  $0.addQueryParameter(name: "autosignout", value: "30")
  $0.body = .json(["username": username, "pwd": pwd])
}
let _ = try await req.fetch()

The code is fully type-safe.

What about the stubber?

Integrated stubber is perfect to write your own test suite:

That's a simple stubber which return the original request as response:

let echoStub = HTTPStubRequest().match(urlRegex: "*").stubEcho()
HTTPStubber.shared.add(stub: echoStub)
HTTPStubber.shared.enable()

Of course you can fully configure your stub with rules (regex, URI template and more):

// This is a custom stubber for any post request.
var stub = HTTPStubRequest()
      .stub(for: .post, { response in
        response.responseDelay = 5
        response.headers = HTTPHeaders([
          .contentType: HTTPContentType.bmp.rawValue,
          .contentLength: String(fileSize,
        ])
        response.body = fileContent
      })
HTTPStubber.shared.add(stub: stub)

That's all!

Feature Highlights

RealHTTP offers lots of features and customization you can find in our extensive documentation and test suite.
Some of them are:

• Async/Await native support
• Requests queue built-in
• Based upon native URLSession technology
• Advanced retry mechanisms
• Chainable & customizable response validators like Node's Express.js
• Automatic Codable object encoding/decoding
• Customizable decoding of objects

And for pro users:

• Powerful integrated HTTP Stub for your mocks
• Combine publisher adapter
• URI templating system
• Resumable download/uploads with progress tracking
• Native Multipart Form Data support
• Advanced URL connection metrics collector
• SSL Pinning, Basic/Digest Auth
• TSL Certificate & Public Key Pinning
• cURL debugger

Documentation

RealHTTP provides an extensive documentation.

• 1 - Introduction
• 2 - Build & Execute a Request
  • Initialize a Request
    • Standard
    • URI Template
    • Builder Pattern
  • Setup Query Parameters
  • Setup Headers
  • Setup Request Body
    • URL Query Parameters
    • Raw Data & Stream
    • Plain Strings
    • JSON Data
    • Multipart-Form-Data
  • The HTTP Client
    • Shared Client
    • Custom Client
  • Execute a Request
  • Modify a Request
  • Cancel a Request
  • The HTTP Response
    • Decode using Codable & Custom Decoding
    • Decode Raw JSON using JSONSerialization
• 3 - Advanced HTTP Client
  • Why using a custom HTTPClient
  • Validate Responses: Validators
    • Approve the response
    • Fail with error
    • Retry with strategy
  • The Default Validator
  • Alt Request Validator
  • Custom Validators
  • Retry After [Another] Call
  • Retry by modify the original request
• 4 - Handle Large Data Request
  • Track Progress
  • Cancel Downloads with resumable data
  • Resume Downloads
• 5 - Security Options
  • Configure security (SSL/TSL)
  • Self-Signed Certificates
• 6 - Other Debugging Tools
  • cURL Command Output
  • Monitor Connection Metrics
• 7 - HTTP Stubber
  • Using HTTPStubber in your unit tests
  • Stub a Request
  • Stub Matchers
    • Echo Matcher
    • Dynamic Matcher
    • URI Matcher
    • JSON Matcher
    • Body Matcher
    • URL Matcher
    • Custom Matcher
  • Add Ignore Rule
  • Unhandled Rules
  • Bad and down network
    • Simulate Network Conditions
    • Simulate a down network

API Reference

RealHTTP is fully documented at source-code level. You'll get autocomplete with doc inside XCode for free; moreover you can read the full Apple's DoCC Documentation automatically generated thanks to Swift Package Index Project from here:

👉 API REFERENCE

Test Suite

RealHTTP has an extensive unit test suite covering many standard and edge cases, including request build, parameter encoding, queuing, and retries strategies.
See the XCTest suite inside Tests/RealHTTPTests folder.

Requirements

RealHTTP can be installed on any platform which supports:

• iOS 13+, macOS Catalina+, watchOS 6+, tvOS 13+
• Xcode 13.2+
• Swift 5.5+

Installation

Swift Package Manager

Add it as a dependency in a Swift Package, and add it to your Package. Swift:

dependencies: [
  .package(url: "https://github.com/immobiliare/RealHTTP.git", from: "1.0.0")
]

And add it as a dependency of your target:

targets: [
  .target(name: "MyTarget", dependencies: [
    .product(name: "https://github.com/immobiliare/RealHTTP.git", package: "RealHTTP")
  ])
]

In Xcode 11+ you can also navigate to the File menu and choose Swift Packages -> Add Package Dependency..., then enter the repository URL and version details.

CocoaPods

RealHTTP can be installed with CocoaPods by adding pod 'RealHTTP' to your Podfile.

pod 'RealHTTP'

Powered Apps

The fantastic mobile team at ImmobiliareLabs created RealHTTP. We are currently using RealHTTP in all of our products.

If you are using RealHTTP in your app drop us a message.

Support & Contribute

Made with ❤️ by ImmobiliareLabs & Contributors

We'd love for you to contribute to RealHTTP!
If you have questions about using RealHTTP, bugs, and enhancement, please feel free to reach out by opening a GitHub Issue.