javier
0431fb5133
## Summary Updates the library to v4.5.1 of the App Store Connect API, and ships it as a breaking 2.0.0 release with pagination, API key authentication, rate limiting, and a lighter install for consumers. ## Breaking changes - **Minimum platforms:** iOS 14, macOS 11, tvOS 14, watchOS 7, and visionOS 1. - **Toolchain:** Swift 6.0+ (Xcode 16+). The package builds in the Swift 6 language mode. - **Runtime:** requires `swift-openapi-runtime` 1.11.0 or later. ## Changes - **API:** updated the OpenAPI specification to v4.5.1, covering 1,303 operations and 1,473 schemas. - **Pagination:** the spec patch adds the undocumented `cursor` query parameter to the 465 paged operations. `PagedDocumentLinks.nextCursor` reads the cursor from a page, and `PagedSequence` iterates every page. - **Authentication:** `APIKeyTokenProvider` signs ES256 tokens from an API key and reuses each one until a minute before it expires. `BearerAuthMiddleware` now accepts a token provider. - **Rate limiting:** `RateLimitMiddleware` retries `429` responses, waiting for `Retry-After` or backing off exponentially. - **Generated code:** committed to `Sources/ASConnectService/Sources/Public/Generated` instead of generated by a build plugin. Consumers now resolve 4 packages instead of 12, and Xcode no longer asks to trust a plugin. - **Tooling:** - `make oas-download` now downloads, patches, generates, and checks the docs in one go. - New `make oas-generate`, `make oas-validate`, and `make doc-check` targets. - The generator is pinned in `Tools/`, and the DocC plugin is only resolved by the documentation targets. - **Documentation:** the DocC catalog now lists every operation and schema in the spec, and the catalog and README are rewritten for the new APIs. - **Housekeeping:** Apache 2.0 license headers on every Swift file, including `Package.swift` and the tests. Reviewed-on: #5 Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
103 lines
2.6 KiB
Markdown
103 lines
2.6 KiB
Markdown
# ``ASConnectService``
|
|
|
|
A type-safe Swift client for the App Store Connect API.
|
|
|
|
## Overview
|
|
|
|
ASConnectService exposes every endpoint of Apple's App Store Connect API as a Swift method with typed requests and responses. It's generated from the official OpenAPI specification with [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator).
|
|
|
|
### Creating a Client
|
|
|
|
Create a ``Client`` with a server URL, a transport, and a ``BearerAuthMiddleware``. With an API key from App Store Connect, ``APIKeyTokenProvider`` signs the JSON Web Tokens (JWT) the API requires, and renews them before they expire:
|
|
|
|
```swift
|
|
import ASConnectService
|
|
import OpenAPIURLSession
|
|
|
|
let tokenProvider = try APIKeyTokenProvider(
|
|
issuerID: yourIssuerID,
|
|
keyID: yourKeyID,
|
|
privateKey: yourP8FileContents
|
|
)
|
|
|
|
let client = Client(
|
|
serverURL: try Servers.Server1.url(),
|
|
transport: URLSessionTransport(),
|
|
middlewares: [
|
|
BearerAuthMiddleware { try await tokenProvider.token() }
|
|
]
|
|
)
|
|
```
|
|
|
|
To use a token you signed yourself, pass it directly. It expires after 20 minutes at most:
|
|
|
|
```swift
|
|
BearerAuthMiddleware(token: yourJWTToken)
|
|
```
|
|
|
|
### Making API Calls
|
|
|
|
Each endpoint is a method on ``Client``, declared by ``APIProtocol``. It returns an `Output` enum with a case for each documented response:
|
|
|
|
```swift
|
|
let response = try await client.appsGetCollection(query: .init(limit: 10))
|
|
let apps = try response.ok.body.json.data
|
|
```
|
|
|
|
The `ok` property throws for any other response. To handle those, switch over the `Output` cases, such as `.unauthorized` or `.undocumented(statusCode:_:)`.
|
|
|
|
### Fetching More Pages
|
|
|
|
Lists are paged. Iterate a ``PagedSequence`` to fetch each page in turn:
|
|
|
|
```swift
|
|
let pages = PagedSequence(links: \.links) { cursor in
|
|
try await client.appsGetCollection(query: .init(limit: 200, cursor: cursor)).ok.body.json
|
|
}
|
|
|
|
var apps: [Components.Schemas.App] = []
|
|
|
|
for try await page in pages {
|
|
apps += page.data
|
|
}
|
|
```
|
|
|
|
To fetch pages yourself, pass a page's ``Components/Schemas/PagedDocumentLinks/nextCursor`` as the `cursor` of the next request.
|
|
|
|
### Handling Rate Limits
|
|
|
|
Add ``RateLimitMiddleware`` before the authentication middleware to retry `429 Too Many Requests` responses:
|
|
|
|
```swift
|
|
middlewares: [
|
|
RateLimitMiddleware(),
|
|
BearerAuthMiddleware { try await tokenProvider.token() }
|
|
]
|
|
```
|
|
|
|
## Topics
|
|
|
|
### API Client
|
|
|
|
- ``Client``
|
|
- ``APIProtocol``
|
|
|
|
### Authentication
|
|
|
|
- ``BearerAuthMiddleware``
|
|
- ``APIKeyTokenProvider``
|
|
|
|
### Pagination
|
|
|
|
- ``PagedSequence``
|
|
|
|
### Rate Limiting
|
|
|
|
- ``RateLimitMiddleware``
|
|
|
|
### Generated Types
|
|
|
|
- ``Components``
|
|
- ``Operations``
|
|
- ``Servers``
|