diff --git a/Sources/Buildkite/Buildkite.docc/Articles/Authorization.md b/Sources/Buildkite/Buildkite.docc/Articles/Authorization.md index 4aa4043..47a9e41 100644 --- a/Sources/Buildkite/Buildkite.docc/Articles/Authorization.md +++ b/Sources/Buildkite/Buildkite.docc/Articles/Authorization.md @@ -1,9 +1,11 @@ # Authorization -Buildkite supports resources across several different APIs with a variety of versions and authorization interfaces. ``BuildkiteClient`` has built-in support to interoperate between the different APIs from a single client. +Authorizing with Buildkite APIs. ## Overview +Buildkite supports resources across several different APIs with a variety of versions and authorization interfaces. ``BuildkiteClient`` has built-in support to interoperate between the different APIs from a single client. + The most basic means of authorizing with a single service in Buildkite is by the declaration of a fixed token string. The client instance will store a copy of this string in memory and use it with all subsequent requests. ```swift diff --git a/Sources/Buildkite/Buildkite.docc/Articles/GettingStarted.md b/Sources/Buildkite/Buildkite.docc/Articles/GettingStarted.md index 9241b15..34e154f 100644 --- a/Sources/Buildkite/Buildkite.docc/Articles/GettingStarted.md +++ b/Sources/Buildkite/Buildkite.docc/Articles/GettingStarted.md @@ -1,14 +1,14 @@ -# Getting Started with Buildkite +# Getting Started Initialize a client and get started with sending resources by listing all pipelines. ## Overview -// TODO +This article is an overview of how to set up your Buildkite client to interact with the REST API. ### Get Your Access Token -In order to access the Buildkite API you must first create an API access token. Follow Buildkite's [own documentation on managing tokens](https://buildkite.com/docs/apis/managing-api-tokens) for more information on what to do. Keep in mind that securely storing tokens used with this package is the responsibility of the developer. +In order to access the Buildkite API you must first create an API access token. Follow Buildkite's own documentation on [managing API tokens](https://buildkite.com/docs/apis/managing-api-tokens) for more information on what to do. Keep in mind that securely storing tokens used with this package is the responsibility of the developer. ### Create a Buildkite Client diff --git a/Sources/Buildkite/Buildkite.docc/Articles/Webhooks.md b/Sources/Buildkite/Buildkite.docc/Articles/Webhooks.md new file mode 100644 index 0000000..8d6a677 --- /dev/null +++ b/Sources/Buildkite/Buildkite.docc/Articles/Webhooks.md @@ -0,0 +1,9 @@ +# Webhooks + +Responding to webhook events from Buildkite. + +## Overview + +The [Buildkite Webhook API](https://buildkite.com/docs/apis/webhooks) is used to consume lifecycle events from Buildkite in real-time from your server application. + +> Note: This will not be a tutorial to implement a server application, nor one to respond to Buildkite webhook events specifically. The purpose of this article is to inform how to use the helpers this client library provides to make implementing your webhooks easier. This article assumes you know how how to configure a new route in your server and expose it in such a way where Buildkite can communicate with it. diff --git a/Sources/Buildkite/Buildkite.docc/Buildkite.md b/Sources/Buildkite/Buildkite.docc/Buildkite.md index e151b3e..048c8d5 100644 --- a/Sources/Buildkite/Buildkite.docc/Buildkite.md +++ b/Sources/Buildkite/Buildkite.docc/Buildkite.md @@ -13,38 +13,7 @@ The entire publicly documented REST API surface is supported by this package. - - ``BuildkiteClient`` -### Resources - -- ``AccessToken/Resources`` -- ``Agent/Resources`` -- ``AgentMetrics/Resources`` -- ``Annotation/Resources`` -- ``Artifact/Resources`` -- ``Build/Resources`` -- ``Emoji/Resources`` -- ``Job/Resources`` -- ``Meta/Resources`` -- ``Organization/Resources`` -- ``Pipeline/Resources`` -- ``Team/Resources`` -- ``TestAnalytics/Resources`` -- ``User/Resources`` -- ``Followable`` -- ``Resource`` - -### GraphQL - -- -- ``GraphQL`` -- ``JSONValue`` - -### Pagination - -- ``Page`` -- ``PageOptions`` -- ``PaginatedResource`` - -### Models +### REST API - ``AccessToken`` - ``Agent`` @@ -52,6 +21,7 @@ The entire publicly documented REST API surface is supported by this package. - ``Artifact`` - ``Build`` - ``Emoji`` +- ``Followable`` - ``Job`` - ``Meta`` - ``Organization`` @@ -59,13 +29,43 @@ The entire publicly documented REST API surface is supported by this package. - ``Team`` - ``User`` -### Advanced +### Authorization - +- ``TokenProvider`` + +#### Pagination + +- ``Page`` +- ``PageOptions`` +- ``PaginatedResource`` + +### GraphQL API + +- +- ``GraphQL`` +- ``JSONValue`` + +### Agent API + +- ``AgentMetrics`` + +### Test Analytics API + +- ``TestAnalytics`` +- ``Trace`` + +### Webhook API + +- +- ``WebhookEvent`` + +### Advanced + - ``Configuration`` - ``APIVersion`` +- ``Resource`` - ``Transport`` -- ``TokenProvider`` - ``Response`` - ``StatusCode`` - ``BuildkiteError`` diff --git a/Sources/Buildkite/Buildkite.docc/Extensions/AccessToken.Resources.md b/Sources/Buildkite/Buildkite.docc/Extensions/AccessToken.Resources.md deleted file mode 100644 index c6c3b8b..0000000 --- a/Sources/Buildkite/Buildkite.docc/Extensions/AccessToken.Resources.md +++ /dev/null @@ -1,12 +0,0 @@ -# ``Buildkite/AccessToken/Resources`` - -## Topics - -### Resources - -- ``Get`` -- ``Revoke`` - -### Models - -- ``AccessToken`` diff --git a/Sources/Buildkite/Buildkite.docc/Extensions/Organization.Resources.md b/Sources/Buildkite/Buildkite.docc/Extensions/Organization.Resources.md deleted file mode 100644 index 71124ef..0000000 --- a/Sources/Buildkite/Buildkite.docc/Extensions/Organization.Resources.md +++ /dev/null @@ -1,12 +0,0 @@ -# ``Buildkite/Organization/Resources`` - -## Topics - -### Resources - -- ``List`` -- ``Get`` - -### Models - -- ``Organization`` diff --git a/Sources/Buildkite/Buildkite.docc/Extensions/Pipeline.Resources.md b/Sources/Buildkite/Buildkite.docc/Extensions/Pipeline.Resources.md deleted file mode 100644 index 0022967..0000000 --- a/Sources/Buildkite/Buildkite.docc/Extensions/Pipeline.Resources.md +++ /dev/null @@ -1,19 +0,0 @@ -# ``Buildkite/Pipeline/Resources`` - -## Topics - -### Resources - -- ``List`` -- ``Get`` -- ``Create`` -- ``CreateVisualSteps`` -- ``Update`` -- ``Archive`` -- ``Unarchive`` -- ``Delete`` -- ``CreateWebhook`` - -### Models - -- ``Pipeline`` diff --git a/Sources/Buildkite/Buildkite.docc/Extensions/Team.Resources.md b/Sources/Buildkite/Buildkite.docc/Extensions/Team.Resources.md deleted file mode 100644 index 718c38c..0000000 --- a/Sources/Buildkite/Buildkite.docc/Extensions/Team.Resources.md +++ /dev/null @@ -1,11 +0,0 @@ -# ``Buildkite/Team/Resources`` - -## Topics - -### Resources - -- ``List`` - -### Models - -- ``Team`` diff --git a/Sources/Buildkite/Buildkite.docc/Extensions/User.Resources.md b/Sources/Buildkite/Buildkite.docc/Extensions/User.Resources.md deleted file mode 100644 index da50a6a..0000000 --- a/Sources/Buildkite/Buildkite.docc/Extensions/User.Resources.md +++ /dev/null @@ -1,11 +0,0 @@ -# ``Buildkite/User/Resources`` - -## Topics - -### Resources - -- ``Me`` - -### Models - -- ``User`` diff --git a/Sources/Buildkite/Models/WebhookEvent.swift b/Sources/Buildkite/Models/WebhookEvent.swift index 5cd1f06..31d735e 100644 --- a/Sources/Buildkite/Models/WebhookEvent.swift +++ b/Sources/Buildkite/Models/WebhookEvent.swift @@ -13,10 +13,10 @@ import FoundationNetworking #endif public enum WebhookEvent: Codable, Equatable { - case ping(WebhookEvents.Ping) - case build(WebhookEvents.Build) - case job(WebhookEvents.Job) - case agent(WebhookEvents.Agent) + case ping(Ping) + case build(Build) + case job(Job) + case agent(Agent) private enum Unassociated: String, Codable { case ping @@ -41,13 +41,13 @@ public enum WebhookEvent: Codable, Equatable { let event = try container.decode(Unassociated.self, forKey: .event) switch event { case .ping: - self = .ping(try WebhookEvents.Ping(from: decoder)) + self = .ping(try Ping(from: decoder)) case .buildScheduled, .buildRunning, .buildFinished: - self = .build(try WebhookEvents.Build(from: decoder)) + self = .build(try Build(from: decoder)) case .jobScheduled, .jobStarted, .jobFinished, .jobActivated: - self = .job(try WebhookEvents.Job(from: decoder)) + self = .job(try Job(from: decoder)) case .agentConnected, .agentLost, .agentDisconnected, .agentStopping, .agentStopped: - self = .agent(try WebhookEvents.Agent(from: decoder)) + self = .agent(try Agent(from: decoder)) } } @@ -67,9 +67,22 @@ public enum WebhookEvent: Codable, Equatable { private enum CodingKeys: String, CodingKey { case event } -} -public enum WebhookEvents { + public struct Service: Codable, Equatable, Identifiable { + public var id: UUID + public var provider: String + public var settings: Settings + + public struct Settings: Codable, Equatable { + public var url: URL + } + } + + public struct Sender: Codable, Equatable, Identifiable { + public var id: UUID + public var name: String + } + public struct Ping: Codable, Equatable { /// The notification service that sent this webhook public var service: Service @@ -142,58 +155,3 @@ public enum WebhookEvents { } } } - -public struct Service: Codable, Equatable, Identifiable { - public var id: UUID - public var provider: String - public var settings: Settings - - public struct Settings: Codable, Equatable { - public var url: URL - } -} - -public struct Sender: Codable, Equatable, Identifiable { - public var id: UUID - public var name: String -} - - -// Received POST { -// host: '3424-2601-192-8600-bfc0-a963-fc8-ece3-46b8.ngrok.io', -// 'user-agent': 'Buildkite-Request', -// 'content-length': '772', -// accept: '*/*', -// 'accept-encoding': 'gzip;q=1.0,deflate;q=0.6,identity;q=0.3', -// 'content-type': 'application/json', -// 'x-buildkite-event': 'ping', -// 'x-buildkite-request': '01813932-4ac5-490a-82cd-eb6bcb2b55b6', -// 'x-buildkite-token': '62d32cdc0687926d9c556dff46a6f0e8', -// 'x-datadog-parent-id': '3879493372906842722', -// 'x-datadog-sampling-priority': '0', -// 'x-datadog-trace-id': '2090185261397568562', -// 'x-forwarded-for': '100.24.182.113', -// 'x-forwarded-proto': 'https' -// } { -// event: 'ping', -// service: { -// id: '69774b46-b443-4ed9-8ee5-7817f9d5d3d6', -// provider: 'webhook', -// settings: { -// url: 'https://3424-2601-192-8600-bfc0-a963-fc8-ece3-46b8.ngrok.io' -// } -// }, -// organization: { -// id: '19ab06b9-17cd-4937-a44b-834976e5f894', -// graphql_id: 'T3JnYW5pemF0aW9uLS0tMTlhYjA2YjktMTdjZC00OTM3LWE0NGItODM0OTc2ZTVmODk0', -// url: 'https://api.buildkite.com/v2/organizations/asky', -// web_url: 'https://buildkite.com/asky', -// name: 'asky', -// slug: 'asky', -// agents_url: 'https://api.buildkite.com/v2/organizations/asky/agents', -// emojis_url: 'https://api.buildkite.com/v2/organizations/asky/emojis', -// created_at: '2020-03-14T20:04:43.567Z', -// pipelines_url: 'https://api.buildkite.com/v2/organizations/asky/pipelines' -// }, -// sender: { id: 'df71cc10-3cf0-49b0-9acb-5882342ca649', name: 'Aaron Sky' } -// }