You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ The purpose of Endpoints is to, in a type-safe way, define how to create a `URLR
12
12
13
13
The basic process for defining an Endpoint starts with defining a value conforming to `Endpoint`. With the `Endpoint` protocol, you are encapsulating the definition of the endpoint, all the properties that are plugged into the definition and the types for parsing the response. Within the `Endpoint`, the `definition` static var serves as an immutable definition of the server's endpoint and how the variable pieces of the `Endpoint` should fit together when making the full request.
14
14
15
-
To get started, first create a type (struct or class) conforming to `Endpoint`. There are only two required elements to conform: defining the `Response` and creating the `Definition`.
15
+
To get started, first create a type (struct or class) conforming to `Endpoint`. There are only two required elements to conform: defining the `Response` and creating the ``Definition``.
16
16
17
17
`Endpoints` and `Definitions` do not contain base URLs so that these requests can be used on different environments. Environments are defined as conforming to the `EnvironmentType` and implement a `baseURL` as well as an optional `requestProcessor` which has a final hook before `URLRequest` creation to modify the `URLRequest` to attach authentication or signatures.
/// The response type received from the server. Note that this is just type information which helpers, such as the built-in `URLSession` extensions,
52
+
/// The response type received from the server.
53
+
///
54
+
/// This conveys type information which helpers, such as the built-in ``Foundation/URLSession`` extensions,
53
55
/// can use to know how to handle particular types. For instance, if this type conforms to `Decodable`, then a JSON decoder is used
54
56
/// on the data coming from the server. If it's typealiased to `Void`, then the extension can know to ignore the response. If it's `Data`, then it can deliver the
55
57
/// response data unmodified.
56
58
associatedtypeResponse
57
59
58
-
/// The type representing the `Decodable` error response from the server. Defaults to an empty `Decodable` struct, `EmptyCodable`.
60
+
/// The type representing the `Decodable` error response from the server. Defaults to an empty `Decodable` struct, ``EmptyCodable``.
61
+
///
59
62
/// This can be useful if your server returns a different JSON structure when there's an error versus a success. Often in a project, this can be defined globally
60
-
/// and `typealias` can be used to associate this global type on all `Endpoint`s.
63
+
/// and `typealias` can be used to associate this global type on all ``Endpoint``s.
/// The body type conforming to `Encodable`. Defaults to `EmptyCodable`.
66
+
/// The body type conforming to `Encodable`. Defaults to ``EmptyCodable``.
64
67
associatedtypeBody:Encodable=EmptyCodable
65
68
66
-
/// The values needed to fill the `Definition`'s path.
69
+
/// The values needed to fill the ``Definition``'s path.
70
+
///
71
+
/// If a ``Endpoint/PathComponents`` type is associated, properties of that type can be utilized in the `path` of the ``Endpoint`` using a path string interpolation syntax:
72
+
///
73
+
/// ```swift
74
+
/// struct DeleteEndpoint: Endpoint {
75
+
/// static let definition: Definition<DeleteEndpoint> = Definition(
/// The values needed to fill the `Definition`'s parameters.
92
+
/// The values needed to fill the ``Definition``'s parameters.
93
+
///
94
+
/// A ``Endpoint/ParameterComponents`` type, in a similar way to ``Endpoint/PathComponents``, holds properties that can be referenced in the ``Endpoint`` via ``Parameter`` values in order to define form parameters used in the body or query parameters attached to the URL. The enum type is defined as:
95
+
///
96
+
/// ```swift
97
+
/// public enum Parameter<T> {
98
+
/// case form(String, path: PartialKeyPath<T>)
99
+
/// case formValue(String, value: PathRepresentable)
100
+
/// case query(String, path: PartialKeyPath<T>)
101
+
/// case queryValue(String, value: PathRepresentable)
102
+
/// }
103
+
/// ```
104
+
///
105
+
/// With this enum, either hard-coded values can be injected into the ``Endpoint`` (with ``Parameter/formValue(_:value:)`` or ``Parameter/queryValue(_:value:)``) or key paths can define which reference properties in the ``Endpoint/ParameterComponents`` associated type to define a form or query parameter that is needed at the time of the request.
70
106
associatedtypeParameterComponents=Void
71
107
72
-
/// The values needed to fill the `Definition`'s headers.
108
+
/// The values needed to fill the ``Definition``'s headers.
73
109
associatedtypeHeaderComponents=Void
74
110
75
-
/// The `EncoderType` to use when encoding the body of the request. Defaults to `JSONEncoder`.
111
+
/// The ``EncoderType`` to use when encoding the body of the request. Defaults to `JSONEncoder`.
76
112
associatedtypeBodyEncoder:EncoderType=JSONEncoder
77
-
/// The `DecoderType` to use when decoding the body of the request. Defaults to `JSONDecoder`.
113
+
/// The ``DecoderType`` to use when decoding the body of the request. Defaults to `JSONDecoder`.
/// A `Definition` which pieces together all the components defined in the endpoint.
118
+
/// A ``Definition`` which pieces together all the components defined in the endpoint.
83
119
staticvardefinition:Definition<Self>{get}
84
120
85
121
/// The instance of the associated `Body` type. Must be `Encodable`.
86
122
varbody:Body{get}
87
123
88
-
/// The instance of the associated `PathComponents` type. Used for filling in request data into the path template of the endpoint.
124
+
/// The instance of the associated ``Endpoint/PathComponents`` type. Used for filling in request data into the path template of the endpoint.
89
125
/// If none are necessary, this can be `Void`
90
126
varpathComponents:PathComponents{get}
91
127
92
-
/// The instance of the associated `ParameterComponents` type. Used for filling in request data into the query and form parameters of the endpoint.
128
+
/// The instance of the associated ``Endpoint/ParameterComponents`` type. Used for filling in request data into the query and form parameters of the endpoint.
93
129
varparameterComponents:ParameterComponents{get}
94
130
95
-
/// The instance of the associated `HeaderComponents` type. Used for filling in request data into the headers of the endpoint.
131
+
/// The instance of the associated ``Endpoint/HeaderComponents`` type. Used for filling in request data into the headers of the endpoint.
96
132
varheaderComponents:HeaderComponents{get}
97
133
98
-
/// The decoder instance to use when decoding the associated `Body` type
134
+
/// The decoder instance to use when decoding the associated ``Endpoint/Body`` type
99
135
staticvarbodyEncoder:BodyEncoder{get}
100
136
101
-
/// The decoder instance to use when decoding the associated `ErrorResponse` type
137
+
/// The decoder instance to use when decoding the associated ``Endpoint/ErrorResponse`` type
102
138
staticvarerrorDecoder:ErrorDecoder{get}
103
139
104
-
/// The decoder instance to use when decoding the associated `Response` type
140
+
/// The decoder instance to use when decoding the associated ``Endpoint/Response`` type
105
141
staticvarresponseDecoder:ResponseDecoder{get}
106
142
}
107
143
@@ -140,18 +176,18 @@ public extension Endpoint where BodyEncoder == JSONEncoder {
140
176
141
177
publicstructDefinition<T:Endpoint>{
142
178
143
-
/// The HTTP method of the Endpoint
179
+
/// The HTTP method of the ``Endpoint``
144
180
publicletmethod:Method
145
181
/// A template including all elements that appear in the path
146
182
publicletpath:PathTemplate<T.PathComponents>
147
-
/// The parameters (form and query) that are included in the Definition
183
+
/// The parameters (form and query) that are included in the ``Definition``
Endpoints is a small library for creating statically and strongly-typed definitions of endpoints with paths, methods, inputs and outputs.
4
+
5
+
## Overview
6
+
7
+
The purpose of Endpoints is to, in a type-safe way, define how to create a `URLRequest` from typed properties and, additionally, define how a response for the request should be handled. The library not only includes the ability to create these requests in a type-safe way, but also includes helpers to perform the requests using ``Foundation/URLSession``. Endpoints does not try to wrap the URL loading system to provide features on top of it like Alamofire. Instead, Endpoints focuses on defining endpoints and associated data to produce a request as a URLRequest object to be plugged into vanilla ``Foundation/URLSession``s. However, this library could be used in conjunction with Alamofire if desired.
0 commit comments