SimpleHTTP


Make HTTP API calls easier. Built on top of URLSession.
Installation
Use Swift Package Manager to install the library:
dependencies: [
.package(url: "https://github.com/pjechris/SimpleHTTP", from: "0.4.0"),
]
The package come with 2 modules:
SimpleHTTP
which bring the full framework API described in this README
SimpleHTTPFoundation
which only bring a few addition to Foundation API. See this article or API doc to have a glimpse of what is provided.
Basic Usage
Building a request
You make requests by creating Request
objects. You can either create them manually or provide static definition by extending Request
:
extension Request {
static let func login(_ body: UserBody) -> Request<UserResponse> {
.post("login", body: body)
}
}
This defines a Request.login(_:)
method which create a request targeting “login” path by sending a UserBody
and expecting a UserResponse
as response.
Sending a request
You can use your request along URLSession
by converting it into a URLRequest
by calling request.toURLRequest(encoder:relativeTo:accepting)
.
You can also use a Session
object. Session
is somewhat similar to URLSession
but providing additional functionalities:
- encoder/decoder for all requests
- error handling
- ability to intercept requests
let session = Session(
baseURL: URL(string: "https://github.com")!,
encoder: JSONEncoder(),
decoder: JSONDecoder()
)
try await session.response(for: .login(UserBody(username: "pjechris", password: "MyPassword")))
A few words about Session:
baseURL
will be prepended to all call paths
- You can skip encoder and decoder if you use JSON
- You can provide a custom
URLSession
instance if ever needed
Send a body
Request support two body types:
Encodable
To send an Encodable object just set it as your Request body:
struct UserBody: Encodable {}
extension Request {
static func login(_ body: UserBody) -> Request<LoginResponse> {
.post("login", body: body)
}
}
Multipart
You can create multipart content from two kind of content
- From a disk file (using a
URL
)
- From raw content (using
Data
)
First example show how to create a request sending an audio file as request body:
extension Request {
static func send(audioFile: URL) throws -> Request<SendAudioResponse> {
var multipart = MultipartFormData()
try multipart.add(url: audioFile, name: "define_your_name")
return .post("v1/sendAudio", body: multipart)
}
}
Second example show same request but this time audio file is just some raw unknown data:
static func send(audioFile: Data) throws -> Request<SendAudioResponse> {
var multipart = MultipartFormData()
try multipart.add(data: audioFile, name: "your_name", mimeType: "audioFile_mimeType")
return .post("v1/sendAudio", body: multipart)
}
}
Note you can add multiple contents inside a MultipartFormData
. For instance here we send both a audio file and an image:
extension Request {
static func send(audio: URL, image: Data) throws -> Request<SendAudioImageResponse> {
var multipart = MultipartFormData()
try multipart.add(url: audio, name: "define_your_name")
try multipart.add(data: image, name: "your_name", mimeType: "image_mimeType")
return .post("v1/send", body: multipart)
}
}
Constant paths
You can declare constant paths if needed (refer to Path documentation to see more):
extension Path {
static let login: Path = "login"
}
extension Request {
static let func login(_ body: UserBody) -> Request<UserResponse> {
.post(.login, body: body)
}
}
Interceptor
When using Session you can add automatic behavior to your requests/responses using Interceptor
like authentication, logging, request retrying, etc…
RequestInterceptor
RequestInterceptor
allows to adapt and/or retry a request:
adaptRequest
method is called before making a request allowing you to transform it adding headers, changing path, …
rescueRequestError
is called whenever the request fail. You’ll have a chance to retry the request. This can be used to re-authenticate the user for instance
ResponseInterceptor
ResponseInterceptor
is dedicated to intercept and server responses:
adaptResponse
change the server output
receivedResponse
notify about the server final response (a valid output or error)
SimpleHTTP
Make HTTP API calls easier. Built on top of URLSession.
Installation
Use Swift Package Manager to install the library:
The package come with 2 modules:
SimpleHTTP
which bring the full framework API described in this READMESimpleHTTPFoundation
which only bring a few addition to Foundation API. See this article or API doc to have a glimpse of what is provided.Basic Usage
Building a request
You make requests by creating
Request
objects. You can either create them manually or provide static definition by extendingRequest
:This defines a
Request.login(_:)
method which create a request targeting “login” path by sending aUserBody
and expecting aUserResponse
as response.Sending a request
You can use your request along
URLSession
by converting it into aURLRequest
by callingrequest.toURLRequest(encoder:relativeTo:accepting)
.You can also use a
Session
object.Session
is somewhat similar toURLSession
but providing additional functionalities:A few words about Session:
baseURL
will be prepended to all call pathsURLSession
instance if ever neededSend a body
Request support two body types:
Encodable
To send an Encodable object just set it as your Request body:
Multipart
You can create multipart content from two kind of content
URL
)Data
)First example show how to create a request sending an audio file as request body:
Second example show same request but this time audio file is just some raw unknown data:
Note you can add multiple contents inside a
MultipartFormData
. For instance here we send both a audio file and an image:Constant paths
You can declare constant paths if needed (refer to Path documentation to see more):
Interceptor
When using Session you can add automatic behavior to your requests/responses using
Interceptor
like authentication, logging, request retrying, etc…RequestInterceptor
RequestInterceptor
allows to adapt and/or retry a request:adaptRequest
method is called before making a request allowing you to transform it adding headers, changing path, …rescueRequestError
is called whenever the request fail. You’ll have a chance to retry the request. This can be used to re-authenticate the user for instanceResponseInterceptor
ResponseInterceptor
is dedicated to intercept and server responses:adaptResponse
change the server outputreceivedResponse
notify about the server final response (a valid output or error)