GitHub onderhoudt de grootste publiek beschikbare OpenAPI-beschrijving — meer dan 1.000 endpoints over repositories, issues, pull requests, actions, checks, packages en de GraphQL-gateway. Voer hem in sgcOpenAPI en lever een typed Delphi-unit op die je applicatie kan gebruiken om elke GitHub-workflow aan te sturen die de REST-API blootstelt.
GitHub levert een volledig onderhouden OpenAPI 3-beschrijving onder de MIT-licentie. sgcOpenAPI parset hem en levert een enkele Pascal-unit op die compileert op Delphi 7 t/m RAD Studio 13.
Personal access token, GitHub App JWT, OAuth
sgcOpenAPI_GitHub
Windows, macOS, Linux, iOS, Android
GitHub publiceert twee smaken van de spec — api.github.com.json voor de publieke hosted service en ghes-3.x.json voor GitHub Enterprise Server. Wijs de parser naar degene die je target.
uses sgcOpenAPI_Parser, sgcOpenAPI_Generator; var vParser: TsgcOpenAPIParser; vGen: TsgcOpenAPIGenerator; begin vParser := TsgcOpenAPIParser.Create(nil); try vParser.LoadFromFile('C:\specs\github\api.github.com.json'); Memo1.Lines.Add(Format('GitHub spec: %d paths, %d schemas', [vParser.Paths.Count, vParser.Schemas.Count])); vGen := TsgcOpenAPIGenerator.Create(nil); try vGen.Parser := vParser; vGen.OutputUnit := 'sgcOpenAPI_GitHub'; vGen.OutputFolder := 'C:\Generated\GitHub'; vGen.GroupBy := gbTag; // one class per tag vGen.Generate; finally vGen.Free; end; finally vParser.Free; end; end;
De generator levert een klasse per GitHub-tag op — TsgcGitHub_Repos, TsgcGitHub_Issues, TsgcGitHub_Pulls, TsgcGitHub_Actions, TsgcGitHub_Checks, TsgcGitHub_Packages, TsgcGitHub_OrgsAdmin enzovoort — allemaal in bezit van een top-level TsgcGitHub-facade.
Authenticeer met een personal access token, en tel dan de repositories van de huidige gebruiker op. Paginering wordt afgehandeld door de gegenereerde enumerable wrapper — doe gewoon for...in over het resultaat en de client haalt aanvullende pagina’s op afroep op.
uses sgcOpenAPI_GitHub; var vGH: TsgcGitHub; vRepo: TsgcGitHubRepository; begin vGH := TsgcGitHub.Create(nil); try vGH.Token := 'ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'; vGH.UserAgent := 'sgcDelphi/1.0'; for vRepo in vGH.Repos.ListForAuthenticatedUser( Visibility := 'private', PerPage := 100) do begin Memo1.Lines.Add(Format('%s — %s', [vRepo.FullName, vRepo.Description])); end; finally vGH.Free; end; end;
Twee korte aanroepen — een muterend, een lezend. Beide routes geven dezelfde sterk getypeerde objecten terug die de spec beschrijft.
// Create an issue in repo "octocat/Hello-World" var vIssue: TsgcGitHubIssue; begin vIssue := vGH.Issues.Create( Owner := 'octocat', Repo := 'Hello-World', Title := 'Memory leak in HTTP/2 reader', Body := 'Repro steps: ...', Labels := ['bug', 'http2']); ShowMessage('Filed issue #' + IntToStr(vIssue.Number)); // List open PRs and inspect the head ref for vPR in vGH.Pulls.List( Owner := 'octocat', Repo := 'Hello-World', State := 'open', Sort := 'updated') do begin Memo1.Lines.Add(Format('PR #%d %s — %s', [vPR.Number, vPR.Title, vPR.Head.Ref])); end; end;
Elke tag in de officiele OpenAPI-beschrijving wordt een typed klasse. Elke gedocumenteerde parameter wordt een typed argument.
Repos, Git, Contents, Branches, Tags, Releases, Forks. Lees, schrijf en verwijder bestanden. Maak branches, beheer protection rules, stel releases op en publiceer ze.
Issues, Pulls, Reviews, Comments, Reactions, Labels, Milestones, Assignees. Het volledige collaboration-oppervlak.
Actions, WorkflowRuns, WorkflowJobs, Artifacts, Secrets, Variables, Checks, CheckRuns, CheckSuites — bouw dashboards of draai automatisering op GitHub Actions-data.
Packages, PackageVersions — beheer npm-, NuGet-, Maven-, RubyGems- en container-packages vanuit Delphi.
Orgs, Teams, Members, Memberships, OrgsAdmin voor owner-only-operaties zoals SCIM-provisioning.
Apps, Installations, AppManifests — installeer GitHub Apps programmatisch en munt kortlevende installation-tokens.
GitHub dwingt een uurlijkse rate limit af (5.000 requests/uur met een token, 60 ongeauthenticeerd). De gegenereerde client slaat de laatste ETag voor elke GET-response op — hergebruik ze door IfNoneMatch in te stellen bij de volgende aanroep om een gratis 304-response te krijgen.
Voor GitHub App-installaties wissel je een JWT (ondertekend met de private key van je app) in voor een 1-uur installation-token. Gebruik de Apps.CreateInstallationAccessToken-methode en vernieuw het token voordat het verloopt.
Het Issues.ListEventsForTimeline-endpoint geeft een discriminated union van tientallen event-types terug. De gegenereerde unit levert een basisklasse en een afstammeling per variant — downcast op basis van de Event-property.
Hoe de onderliggende parser real-world OpenAPI 3.x-specificaties afhandelt.
Lees post →De bijbehorende blog-post die zowel de client-wrapper als de parser-internals introduceert.
Lees post →