{"id":16755768,"url":"https://github.com/otaviocc/microclient","last_synced_at":"2025-04-10T16:50:33.648Z","repository":{"id":118185143,"uuid":"420656447","full_name":"otaviocc/MicroClient","owner":"otaviocc","description":"µ network client","archived":false,"fork":false,"pushed_at":"2023-06-21T16:19:57.000Z","size":550,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T14:40:44.886Z","etag":null,"topics":["api","api-client","client","combine","microclient","network","networking","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/otaviocc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-24T10:48:53.000Z","updated_at":"2022-07-21T12:20:11.000Z","dependencies_parsed_at":"2023-09-28T17:11:23.814Z","dependency_job_id":null,"html_url":"https://github.com/otaviocc/MicroClient","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaviocc%2FMicroClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaviocc%2FMicroClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaviocc%2FMicroClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaviocc%2FMicroClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/otaviocc","download_url":"https://codeload.github.com/otaviocc/MicroClient/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248255732,"owners_count":21073371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","client","combine","microclient","network","networking","swift"],"created_at":"2024-10-13T03:23:43.981Z","updated_at":"2025-04-10T16:50:33.639Z","avatar_url":"https://github.com/otaviocc.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MicroClient\n\n**Simple** and **lightweight** network client which can be used by all sorts of projects.\n\n## Components\n\nThe main components are:\n\n* ``NetworkClient``: The network client itself. The client is a concrete implementation of the ``NetworkClientProtocol`` protocol.\n* ``NetworkRequest``: The request definition.\n* ``NetworkResponse``: The network response, containing both the `URLResponse` and the decodable response.\n* ``NetworkConfiguration``: The network client configuration.\n\n### Network Client\n\nThe network client interface is initialized with its configuration, ``NetworkConfiguration``, and contains a method which performs the network request, `NetworkClientProtocol.run(_:)`.\n\n```swift\npublic protocol NetworkClientProtocol {\n    init(configuration: NetworkConfiguration)\n\n    func run\u003cRequestModel, ResponseModel\u003e(\n        _ networkRequest: NetworkRequest\u003cRequestModel, ResponseModel\u003e\n    ) async throws -\u003e NetworkResponse\u003cResponseModel\u003e\n}\n```\n\n### Network Request\n\nThe network request contains two types, `RequestModel` and `ResponseModel`. These types conform to `Encodable` and `Decodable` protocols, respectively.\n\n```swift\npublic struct NetworkRequest\u003c\n    RequestModel,\n    ResponseModel\n\u003e where RequestModel: Encodable, ResponseModel: Decodable\n```\n\nThe network request can be initialized with several properties, most of them optional, used to override the network configuration when applicable. E.g., the network client might need to use a different decoder or encoder for the request, or might require additional headers. \n\n### Network Response\n\nAs previously mentioned, the network request contains both the original `URLResponse` and the payload decodable to `ResponseModel`.\n\n```swift\npublic struct NetworkResponse\u003cResponseModel\u003e {\n    public let value: ResponseModel\n    public let response: URLResponse\n}\n```\n\n### Configuration\n\nThe network client can be configured with default encoders and decoders, hostname, session, etc...\n\n```swift\npublic final class NetworkConfiguration {\n\n    /// The session used to perform the network requests.\n    public let session: URLSession\n\n    /// The default JSON decoder. It can be overwritten by\n    /// individual requests, if necessary.\n    public let defaultDecoder: JSONDecoder\n\n    /// The default JSON encoder. It can be overwritten by\n    /// individual requests, if necessary.\n    public let defaultEncoder: JSONEncoder\n\n    /// The base URL component.\n    /// E.g., `https://hostname.com/api/v3`\n    public let baseURL: URL\n\n    /// The interceptor called right before performing the\n    /// network request. Can be used to modify the `URLRequest`\n    /// if necessary.\n    public var interceptor: ((URLRequest) -\u003e URLRequest)?\n}\n```\n\n## Building Requests\n\nRequests are built by creating ``NetworkRequest`` instances. Below, a simple `GET` requests which retrieves a list of posts bookmarked by the user.  The network response is `PostsResponse`, which conforms to the `Decodable` protocol.\n\n```swift\nlet request = NetworkRequest\u003cVoidRequest, PostsResponse\u003e(\n    path: \"/posts/bookmarks\",\n    method: .get\n}\n```\n\nThe `NetworkRequest` allows custom encoders and decoders for the request, overriding the default ones from the `NetworkConfiguration`.\n\n```swift\npublic struct NetworkRequest\u003c\n    RequestModel,\n    ResponseModel\n\u003e where RequestModel: Encodable, ResponseModel: Decodable {\n\n    /// The request `/path`, used in combination with the\n    /// `NetworkConfiguration.baseURL`.\n    public let path: String?\n\n    /// The HTTP request method.\n    public let method: HTTPMethod\n\n    /// The query URL component as an array of name/value pairs.\n    public let queryItems: [URLQueryItem]?\n\n    /// The data sent as the message body of a request as\n    /// form item as for an HTTP POST request.\n    public let formItems: [URLFormItem]?\n\n    /// The base URL used for the request. If present, it overrides\n    /// `NetworkConfiguration.baseURL`.\n    public let baseURL: URL?\n\n    /// The data sent as the message body of a request, such\n    /// as for an HTTP POST request.\n    public let body: RequestModel?\n\n    /// The decoder used to decode the `ResponseModel`. If not not\n    /// specified `NetworkConfiguration.defaultDecoder`.\n    /// is used instead.\n    public let decoder: JSONDecoder?\n\n    /// The encoder used to encode the `RequestModel`. If not not\n    /// specified `NetworkConfiguration.defaultEncoder`.\n    /// is used instead.\n    public let encoder: JSONEncoder?\n\n    /// A dictionary containing additional header fields\n    /// for the request.\n    public let additionalHeaders: [String: String]?\n}\n```\n\n## Performing Requests\n\nA network requests is performed by calling  `NetworkClientProtocol.run(_:)`.\n\n```swift\n// Returns NetworkRequest\u003cVoidRequest, PostsResponse\u003e\nlet bookmarksRequest = PostsAPIFactory.makeBookmarksRequest()\n\n// Returns NetworkResponse\u003cPostsResponse\u003e \nlet bookmarksResponse = try await client.run(bookmarksRequest)\n```\n\n## Examples\n\n* [MicroblogAPI](https://github.com/otaviocc/MicroblogAPI) uses MicroClient to access Micro.blog APIs. It also implements photo upload - `multipart/form-data` - using MicroClient.\n* [MicroPinboardAPI](https://github.com/otaviocc/MicroPinboardAPI) uses MicroClient to access Pinboard's APIs.\n* [MicropubAPI](https://github.com/otaviocc/MicropubAPI) uses MicroClient to access Micropub APIs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotaviocc%2Fmicroclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fotaviocc%2Fmicroclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotaviocc%2Fmicroclient/lists"}