https://github.com/ricky-stone/swiftrest
SwiftRest is a lightweight, easy-to-use Swift package for building REST API clients. It provides a flexible and robust solution for sending HTTP requests with built-in support for retries, base headers, and per-request authorization tokens—all while using a consistent JSON encoding/decoding strategy.
https://github.com/ricky-stone/swiftrest
async-await concurrency ios rest-api restapi restful-api spm swift swift6 swiftui xcode
Last synced: 18 days ago
JSON representation
SwiftRest is a lightweight, easy-to-use Swift package for building REST API clients. It provides a flexible and robust solution for sending HTTP requests with built-in support for retries, base headers, and per-request authorization tokens—all while using a consistent JSON encoding/decoding strategy.
- Host: GitHub
- URL: https://github.com/ricky-stone/swiftrest
- Owner: ricky-stone
- Created: 2025-03-22T23:50:41.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-03-29T20:15:10.000Z (28 days ago)
- Last Synced: 2025-04-05T10:04:16.318Z (22 days ago)
- Topics: async-await, concurrency, ios, rest-api, restapi, restful-api, spm, swift, swift6, swiftui, xcode
- Language: Swift
- Homepage:
- Size: 52.7 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SwiftRest
[](https://swiftpackageindex.com/ricky-stone/SwiftRest)
[](https://swiftpackageindex.com/ricky-stone/SwiftRest)
SwiftRest is a lightweight, easy-to-use Swift package for building REST API clients. It provides a flexible and robust solution for sending HTTP requests with built-in support for retries, base headers, and per-request authorization tokens—all while using a consistent JSON encoding/decoding strategy.
---
## Features
- **Simple API:** Easily construct and execute HTTP requests.
- **Retry Support:** Configure automatic retry behavior for transient errors.
- **Base Headers:** Define client-level headers that apply to every request.
- **Authorization:** Add per-request Bearer tokens for secure endpoints.
- **JSON Handling:** Built-in JSON encoding and decoding using a dedicated JSON helper.
- **Comprehensive Error Handling:** Detailed error types for troubleshooting.
---
## Requirements
- **Swift:** 5.5+
- **Platforms:** iOS 13+, macOS 10.15+, or equivalent
- **Xcode:** 13+
---
## Installation
Add SwiftRest to your project using the Swift Package Manager.
1. In Xcode, navigate to **File > Swift Packages > Add Package Dependency…**
2. Enter the repository URL: https://github.com/ricky-stone/SwiftRest.git
3. Follow the prompts to complete the integration.
---
## Usage
### Importing the Package
Begin by importing SwiftRest in your Swift file:
```swift
import SwiftRest
```
Creating a Request
Create a SwiftRestRequest instance by specifying the endpoint path and HTTP method. Then, customize the request by adding headers, URL parameters, a JSON body, an authorization token, and retry configurations as needed.
```swift
// Create a GET request to the "api/v1/users" endpoint
var request = SwiftRestRequest(path: "api/v1/users", method: .get)
// Optionally add a custom header
request.addHeader("Custom-Header", "Value")
// Optionally add URL parameters
request.addParameter("page", "1")
// Optionally add an authorization token (will be sent as a Bearer token)
request.addAuthToken("your_auth_token_here")
// Optionally configure retry behavior (3 attempts with a 0.5-second delay between retries)
request.configureRetries(maxRetries: 3, retryDelay: 0.5)
```
Initializing the REST Client
Initialize the SwiftRestClient with your base URL. You can also specify base headers that apply to every request made through this client.
```swift
let client = SwiftRestClient("https://api.example.com")
```
Executing a Request
SwiftRest provides two methods for executing requests asynchronously:
1. Executing with a Response
This method decodes the response into a specified type.
```swift
// Define a model for the expected response. The model must conform to Decodable & Sendable.
struct User: Decodable, Sendable {
let id: Int
let name: String
}
// Execute the request and decode the response.
do {
let response: SwiftRestResponse = try await client.executeAsyncWithResponse(request)
if response.isSuccess, let user = response.data {
print("User Name: \(user.name)")
} else {
print("Request failed with status code: \(response.statusCode)")
}
} catch {
print("Error executing request: \(error)")
}
```
2. Executing without a Response
For requests that do not expect any response payload.
```swift
do {
try await client.executeAsyncWithoutResponse(request)
print("Request executed successfully")
} catch {
print("Error executing request: \(error)")
}
```
Error Handling
SwiftRest defines a set of error types in `SwiftRestClientError` for various failure scenarios:
- **invalidBaseURL:** The provided base URL is invalid.
- **invalidURLComponents:** URL components could not be properly constructed.
- **invalidFinalURL:** The final URL after appending query parameters is invalid.
- **invalidHTTPResponse:** The HTTP response is missing or malformed.
- **missingContentType:** The expected “Content-Type” header is missing.
- **retryLimitReached:** The maximum number of retry attempts has been reached without success.
⸻
Contributing
Contributions are welcome! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request on GitHub.
⸻
License
This project is licensed under the MIT License.
⸻
Acknowledgments
Thank you for using SwiftRest! If you find this package useful, please consider starring the repository and sharing it with your community.
⸻
Happy coding!