96 lines
2.5 KiB
Markdown
96 lines
2.5 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. Pass a page's ``Components/Schemas/PagedDocumentLinks/nextCursor`` as the `cursor` of the next request:
|
|
|
|
```swift
|
|
var apps: [Components.Schemas.App] = []
|
|
var cursor: String?
|
|
|
|
repeat {
|
|
let page = try await client.appsGetCollection(query: .init(limit: 200, cursor: cursor)).ok.body.json
|
|
apps += page.data
|
|
cursor = page.links.nextCursor
|
|
} while cursor != nil
|
|
```
|
|
|
|
### 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``
|
|
|
|
### Rate Limiting
|
|
|
|
- ``RateLimitMiddleware``
|
|
|
|
### Generated Types
|
|
|
|
- ``Components``
|
|
- ``Operations``
|
|
- ``Servers``
|