Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/michaelnisi/patron
JSON HTTP client
https://github.com/michaelnisi/patron
client http json swift
Last synced: about 1 month ago
JSON representation
JSON HTTP client
- Host: GitHub
- URL: https://github.com/michaelnisi/patron
- Owner: michaelnisi
- License: mit
- Created: 2015-11-23T20:04:00.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-06T23:36:30.000Z (almost 2 years ago)
- Last Synced: 2024-05-02T05:35:42.059Z (7 months ago)
- Topics: client, http, json, swift
- Language: Swift
- Homepage:
- Size: 43.8 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Patron [](http://travis-ci.org/michaelnisi/patron)
> Consume JSON HTTP APIs
Programs often communicate over [HTTP](http://httpwg.org/). The de facto standard notation for payloads in this communication is [JSON](http://www.json.org/). The Patron Swift package provides a simple interface to send and receive data to and from HTTP servers. It’s purpose is to reduce redundant client code whilst keeping things simple.
## Symbols
### Classes
- [Patron](#patron-1)
The `Patron` object represents a remote HTTP JSON service endpoint.
### Protocols
- JSONService
The `JSONService` protocol defines a JSON service.
### Structures
- PatronError
## Patron
The `Patron` class is a convenient way to represent a remote HTTP JSON service endpoint. A `Patron` object provides access to a single service on a specific host via `GET` and `POST` HTTP methods. It assumes that payloads in both directions are JSON.
As `Patron` serializes JSON payloads on the calling thread, it’s not a good idea to use it from the main thread, instead I recommend, you run it from within an `Operation`, or a closure dispatched to another queue. Usually there is more work required anyways, serialization obviously, which should be offloaded from the main thread.
### Creating a Client
```swift
init(URL baseURL: URL, session: URLSession, log: OSLog)
```
Creates a client for the service at the specified `URL`.
#### Parameters
- `URL` The URL of the service.
- `session` The session to use for HTTP requests.
- `log` The log to use, the shared disabled log by default.
#### Returns
Returns the newly initialized `Patron` client.
### Issuing GET Requests
```swift
@discardableResult func get(
path: String,
cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) -> URLSessionTask
```
Issues a `GET` request to the remote API.
#### Parameters
- `path` The URL path including first slash, for example `"/user"`.
- `cb` The callback receiving the JSON result as its first parameter, followed by response, and error. All callback parameters may be `nil`.
#### Returns
An executing `URLSessionTask`.
#### Example
Searching for Swift Repos on GitHub and printing their names.
```swift
import Foundation
import Patron
let github = URL(string: "https://api.github.com")!
let patron = Patron(URL: github, session: URLSession.shared)
patron.get(path: "/search/repositories?q=language:swift") { json, res, er in
let repos = json!["items"] as! [[String : AnyObject]]
let names = repos.map { $0["name"]! }
print(names)
}
```
Find this example in the Playground included in this repo.
#### Query String
If you don‘t feel like stringing together the path yourself, you can pass URL query items.
```swift
@discardableResult func get(
path: String,
with query: [URLQueryItem],
cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) throws -> URLSessionTask
```
Issues a `GET` request with query string to the remote API.
#### Parameters
- `path` The URL path including first slash, for example `"/user"`.
- `query` An array of URL query items from [Foundation](https://developer.apple.com/documentation/foundation/urlqueryitem).
- `cb` The callback receiving the JSON result as its first parameter, followed by response, and error. All callback parameters may be `nil`.
#### Returns
An executing `URLSessionTask`.
#### Additional Parameters
For more control, there‘s an alternative method with `allowsCellularAccess` and `cachePolicy` parameters.
```swift
@discardableResult func get(
path: String,
allowsCellularAccess: Bool,
cachePolicy: URLRequest.CachePolicy,
cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) -> URLSessionTask
```
- `allowsCellularAccess` `true` if the request is allowed to use cellular radios.
- `cachePolicy` The cache policy of the request.
### Issuing POST Requests
```swift
@discardableResult func post(
path: String,
json: AnyObject,
cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) throws -> URLSessionTask
```
Issues a `POST` request to the remote API.
#### Parameters
- `path` The URL path.
- `json` The payload to send as the body of this request.
- `cb` The callback receiving the JSON result as its first parameter, followed by response, and error. All callback parameters may be `nil`.
#### Returns
An executing `URLSessionTask`.
#### Throws
`PatronError.InvalidJSON`, if the potential `json` payload is
not serializable to JSON by `NSJSONSerialization`.
### Getting Information
```swift
var host: String { get }
```
The hostname of the remote service.
```swift
var status: (Int, TimeInterval)? { get }
```
The last `URLSession` or `JSONSerialization` error code, and the timestamp at which it occured in Unix time, seconds since `00:00:00 UTC on 1 January 1970`. The next successful request resets `status` to `nil`.
## Test
For testing, we run a little Node.js Server – find it in `Tests/Server`.
```
$ make test
```
## Install
📦 Add `https://github.com/michaelnisi/patron` to your package manifest.
## License
[MIT](https://raw.githubusercontent.com/michaelnisi/patron/master/LICENSE)