feat(request): [#11] Introduce Endpoint instead of Path (#13)

Author: pjechris

README.md

@@ -22,16 +22,16 @@ extension Request {
 
 And... voila! We defined a `login(_:)` request which will request login endpoint by sending a `UserBody` and waiting for a `UserResponse`. Now it's time to use it.
 
-You can also use an enum to define your Request path:
+You can declare constant endpoints if needed (refer to Endpoint documentation to see more):
 
 ```swift
-enum MyAppEndpoint: String, Path {
-  case login
+extension Endpoint {
+  static let login: Endpoint = "login"
 }
 
 extension Request {
   static let func login(_ body: UserBody) -> Self where Output == UserResponse {
-    .post(MyAppEndpoint.login, body: body)
+    .post(.login, body: body)
   }
 }
 ```

Sources/README.md

@@ -0,0 +1,20 @@
+# Packages
+
+The project is split in two packages:
+
+- SimpleHTTPFoundation
+- SimpleFoundation
+
+## SimpleHTTPFoundation
+
+This package contain extensions on Foundation objects to bring some convenience methods to Foundation that could be used by any network package or project.
+
+Related article: [Designing a lightweight HTTP framework: foundation](https://swiftunwrap.com/article/designing-http-framework-foundation/).
+
+## SimpleHTTP
+
+It contain package true functionalities like Request or Session objects. When building a functionality in this package try to do it in 3 steps:
+
+- Design the new objects
+- Make them interact with Foundation. For instance `Request+URLRequest.swift` bridge from `Request` to `URLRequest`
+- Add pieces to `Session`

Sources/SimpleHTTP/Request/Endpoint.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+/// A endpoint represents a path a request can query to
+///
+/// You can create endpoints using plain String, for instance:
+/// ```swift
+/// extension Endpoint {
+///   static let user = "v1/users"
+/// }
+///
+/// If you want to regroup a set of endpoints you can use your own "namespace" and add a forward declaration in `Endpoint`.
+/// Adding a declaration provide autocompletion when using it in `Request`.
+/// ```swift
+/// enum MyEndpoints {
+///   static let user: Endpoint = "v1/users"
+/// }
+///
+/// extension Endpoint {
+///   static let myEndpoints = MyEndpoints.self
+/// }
+///
+/// let user: Endpoint = .myEndpoints.user
+/// ```
+public struct Endpoint: Equatable, ExpressibleByStringLiteral {
+    /// relative path
+    let path: String
+
+    init(path: String) {
+        self.path = path
+    }
+
+    public init(stringLiteral value: StringLiteralType) {
+        self.init(path: value)
+    }
+
+    public static func ==(lhs: Endpoint, rhs: String) -> Bool {
+        lhs.path == rhs
+    }
+}
+

Sources/SimpleHTTP/Request/Path.swift

@@ -17,33 +17,33 @@ public enum Body {
 /// Highly inspired by https://swiftwithmajid.com/2021/02/10/building-type-safe-networking-in-swift/
 public struct Request<Output> {
 
-    /// request relative path
-    public let path: String
+    /// request relative endpoint
+    public let endpoint: Endpoint
     public let method: Method
     public let body: Body?
     public let query: [String: QueryParam]
     public private(set) var headers: HTTPHeaderFields = [:]
 
-    public static func get(_ path: Path, query: [String: QueryParam] = [:]) -> Self {
-        self.init(path: path, method: .get, query: query, body: nil)
+    public static func get(_ endpoint: Endpoint, query: [String: QueryParam] = [:]) -> Self {
+        self.init(endpoint: endpoint, method: .get, query: query, body: nil)
     }
 
-    public static func post(_ path: Path, body: Body?, query: [String: QueryParam] = [:])
+    public static func post(_ endpoint: Endpoint, body: Body?, query: [String: QueryParam] = [:])
     -> Self {
-        self.init(path: path, method: .post, query: query, body: body)
+        self.init(endpoint: endpoint, method: .post, query: query, body: body)
     }
 
-    public static func put(_ path: Path, body: Body, query: [String: QueryParam] = [:])
+    public static func put(_ endpoint: Endpoint, body: Body, query: [String: QueryParam] = [:])
     -> Self {
-        self.init(path: path, method: .put, query: query, body: body)
+        self.init(endpoint: endpoint, method: .put, query: query, body: body)
     }
 
-    public static func delete(_ path: Path, query: [String: QueryParam] = [:]) -> Self {
-        self.init(path: path, method: .delete, query: query, body: nil)
+    public static func delete(_ endpoint: Endpoint, query: [String: QueryParam] = [:]) -> Self {
+        self.init(endpoint: endpoint, method: .delete, query: query, body: nil)
     }
 
-    private init(path: Path, method: Method, query: [String: QueryParam], body: Body?) {
-        self.path = path.path
+    private init(endpoint: Endpoint, method: Method, query: [String: QueryParam], body: Body?) {
+        self.endpoint = endpoint
         self.method = method
         self.body = body
         self.query = query

Sources/SimpleHTTP/Request/Request.swift

@@ -6,8 +6,8 @@ import FoundationNetworking
 
 extension URL {
     init<Output>(from request: Request<Output>) throws {
-        guard var components = URLComponents(string: request.path) else {
-            throw URLComponents.Error.invalid(path: request.path)
+        guard var components = URLComponents(string: request.endpoint.path) else {
+            throw URLComponents.Error.invalid(endpoint: request.endpoint)
         }
 
         let queryItems = (components.queryItems ?? []) + request.query.queryItems
@@ -24,7 +24,7 @@ extension URL {
 
 extension URLComponents {
     public enum Error: Swift.Error {
-        case invalid(path: String)
+        case invalid(endpoint: Endpoint)
         case cannotGenerateURL(components: URLComponents)
     }
 }

Sources/SimpleHTTP/Request/URL+Request.swift

@@ -1,26 +1,26 @@
 import XCTest
 @testable import SimpleHTTP
 
+extension Endpoint {
+    fileprivate static let test: Endpoint = "test"
+}
+
 class RequestTests: XCTestCase {
-    enum TestEndpoint: String, Path {
-        case test
-    }
-    
     let baseURL = URL(string: "https://google.fr")!
 
     func test_init_withPathAsString() {
-        XCTAssertEqual(Request<Void>.get("hello_world").path, "hello_world")
+        XCTAssertEqual(Request<Void>.get("hello_world").endpoint, "hello_world")
     }
 
     func test_toURLRequest_setHttpMethod() throws {
-        let request = try Request<Void>.post(TestEndpoint.test, body: nil)
+        let request = try Request<Void>.post(.test, body: nil)
             .toURLRequest(encoder: JSONEncoder(), relativeTo: baseURL)
 
         XCTAssertEqual(request.httpMethod, "POST")
     }
 
     func test_toURLRequest_EncodeBody() throws {
-      let request = try Request<Void>.post(TestEndpoint.test, body: .encodable(Body()))
+      let request = try Request<Void>.post(.test, body: .encodable(Body()))
             .toURLRequest(encoder: JSONEncoder(), relativeTo: baseURL)
 
       XCTAssertEqual(request.httpBody, try JSONEncoder().encode(Body()))
@@ -34,7 +34,7 @@ class RequestTests: XCTestCase {
       let name = "swift"
       try multipart.add(url: url, name: name)
 
-      let request = try Request<Void>.post(TestEndpoint.test, body: .multipart(multipart))
+      let request = try Request<Void>.post(.test, body: .multipart(multipart))
             .toURLRequest(encoder: JSONEncoder(), relativeTo: baseURL)
 
       /// We can't use  `XCTAssertEqual(request.httpBody, try multipart.encode)`
@@ -53,7 +53,7 @@ class RequestTests: XCTestCase {
     }
 
     func test_toURLRequest_bodyIsEncodable_FillDefaultHeaders() throws {
-      let request = try Request<Void>.post(TestEndpoint.test, body: .encodable(Body()))
+      let request = try Request<Void>.post(.test, body: .encodable(Body()))
             .toURLRequest(encoder: JSONEncoder(), relativeTo: baseURL)
 
       XCTAssertEqual(request.allHTTPHeaderFields?["Content-Type"], "application/json")
@@ -66,7 +66,7 @@ class RequestTests: XCTestCase {
       let name = "swift"
       try multipart.add(url: url, name: name)
 
-      let request = try Request<Void>.post(TestEndpoint.test, body: .multipart(multipart))
+      let request = try Request<Void>.post(.test, body: .multipart(multipart))
             .toURLRequest(encoder: JSONEncoder(), relativeTo: baseURL)
 
       XCTAssertEqual(request.allHTTPHeaderFields?["Content-Type"], HTTPContentType.multipart(boundary: multipart.boundary).value)

Tests/SimpleHTTPTests/Request/RequestTests.swift

@@ -97,8 +97,8 @@ class SessionAsyncTests: XCTestCase {
     }
 }
 
-private enum Endpoint: String, Path {
-    case test
+private extension Endpoint {
+    static let test: Endpoint = "test"
 }
 
 private struct Content: Codable, Equatable {
@@ -111,11 +111,11 @@ private struct CustomError: Error, Codable, Equatable {
 
 private extension Request {
     static func test() -> Self where Output == Content {
-        .get(Endpoint.test)
+        .get(.test)
     }
 
     static func void() -> Self where Output == Void {
-        .get(Endpoint.test)
+        .get(.test)
     }
 }