Skip to content

Commit 3792643

Browse files
DaveTryonDaveTryon
authored
Add migration guide to V4 API (#1028)
1 parent 7a5d06f commit 3792643

File tree

2 files changed

+101
-0
lines changed

2 files changed

+101
-0
lines changed

‎docs/api-version-4-migration-guide.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Migrating to the version 4 API from the version 3 API
2+
3+
This release includes breaking changes to the API. Most API consumers will be impacted by the [casing changes](#casing-changes). Only a few customers are likely to be impacted by the [functional changes](#functional-changes).
4+
5+
## Casing changes
6+
7+
The cases used in the 3.0 API were very inconsistent. The interfaces and classes that were written very early tended to spell "sbom" as "SBOM" (all caps), while code added later tended to use "Sbom" (Pascal case). Casing of the file names were similarly inconsistent. We decided to take this opportunity to adopt "Sbom" as our standard within the code (this matches the namespace), but still retain "SBOM" as the standalone form in documentation and comments. We haven't yet updated all of the test classes, but that should be a non-issue to users of the API. The "quick and dirty" change in your code is to do a case-sensitive global replacement of "SBOM" with "Sbom". The following table describes the detailed casing changes--this list is intended to be exhaustive and includes interfaces and classes that very few people would ever need to worry about:
8+
9+
### Interfaces
10+
11+
Old name (all caps) | New name (Pascal case)
12+
--- | ---
13+
`ISBOMGenerator` | `ISbomGenerator`
14+
`ISBOMReaderForExternalDocumentReference` | `ISbomReaderForExternalDocumentReference`
15+
`ISBOMValidator` | `ISbomValidator`
16+
`IValidatedSBOM` | `IValidatedSbom`
17+
18+
### Classes
19+
20+
Old name (all caps) | New name (Pascal case)
21+
--- | ---
22+
`ComponentDetectionToSBOMPackageAdapter` | `ComponentDetectionToSbomPackageAdapter`
23+
`InternalSBOMFileInfoDeduplicator` | `InternalSbomFileInfoDeduplicator`
24+
`SBOMApiMetadataProvider` | `SbomApiMetadataProvider`
25+
`SBOMComponentsWalker` | `SbomComponentsWalker`
26+
`SBOMFile` | `SbomFile`
27+
`SBOMFormatExtensions` | `SbomFormatExtensions`
28+
`SBOMMetadata` | `SbomMetadata`
29+
`SBOMPackagesProvider` | `SbomPackagesProvider`
30+
`SBOMReference` | `SbomReference`
31+
`SBOMRelationship` | `SbomRelationship`
32+
`SBOMTelemetry` | `SbomTelemetry`
33+
`SBOMValidationResult` | `SbomValidationResult`
34+
`SPDXSBOMReaderForExternalDocumentReference` | `SPDXSbomReaderForExternalDocumentReference`
35+
`ValidatedSBOM` | `ValidatedSbom`
36+
`ValidatedSBOMFactory` | `ValidatedSbomFactory`
37+
38+
### Methods
39+
40+
Old name (all caps) | New name (Pascal case)
41+
--- | ---
42+
`IInternalMetadataProvider.GetSBOMNamespaceUri` | `IInternalMetadataProvider.GetSbomNamespaceUri`
43+
`IRecorder.RecordSBOMFormat` | `IRecorder.RecordSbomFormat`
44+
`ISBOMGenerator.GetSupportedSBOMSpecifications` | `ISbomGenerator.GetSupportedSbomSpecifications`
45+
`ISBOMReaderForExternalDocumentReference.ParseSBOMFile` | `ISbomReaderForExternalDocumentReference.ParseSbomFile`
46+
`ISbomRedactor.RedactSBOMAsync` | `ISbomRedactor.RedactSbomAsync`
47+
`ManifestInfo.ToSBOMSpecification` | `ManifestInfo.ToSbomSpecification`
48+
`SbomConfigProvider.GetSBOMNamespaceUri` | `SbomConfigProvider.GetSbomNamespaceUri`
49+
`SbomGenerator.GetSupportedSBOMSpecifications` | `SbomGenerator.GetSupportedSbomSpecifications`
50+
`SbomRedactor.RedactSBOMAsync` | `SbomRedactor.RedactSbomAsync`
51+
`SPDXSBOMReaderForExternalDocumentReference.ParseSBOMFile` | `SPDXSbomReaderForExternalDocumentReference.ParseSbomFile`
52+
`TelemetryRecorder.RecordSBOMFormat` | `TelemetryRecorder.RecordSbomFormat`
53+
`ValidatedSBOMFactory.CreateValidatedSBOM` | `ValidatedSbomFactory.CreateValidatedSbom`
54+
55+
### Properties and const values
56+
57+
Old name (all caps) | New name (Pascal case)
58+
--- | ---
59+
`Events.SBOMGenerationWorkflow` | `Events.SbomGenerationWorkflow`
60+
`Events.SBOMParseMetadata` | `Events.SbomParseMetadata`
61+
`Events.SBOMValidationWorkflow` | `Events.SbomValidationWorkflow`
62+
`FileHashes.SBOMFileHash` | `FileHashes.SbomFileHash`
63+
`IAssemblyConfig.DefaultSBOMNamespaceBaseUri` | `IAssemblyConfig.DefaultSbomNamespaceBaseUri`
64+
`MetadataKey.SBOMToolName` | `MetadataKey.SbomToolName`
65+
`MetadataKey.SBOMToolVersion` | `MetadataKey.SbomToolVersion`
66+
`SettingsSource.SBOMApi` | `SettingsSource.SbomApi`
67+
68+
We discussed making a similar change with "SPDX", but ultimately decided to leave "SPDX" as all caps when dealing with interfaces and classes. There are many places in the code where variables use either camel casing or Pascal casing, but none of those should impact code that builds upon our API.
69+
70+
## Functional changes
71+
72+
If you use the Workflows that are documented [here](sbom-tool-api-reference.md), then you will not be impacted by most of the functional changes. You will get the default implementations of the classes, which implement the current API. If, however, you create your own implementations or wrappers based on any of the interfaces exposed in our API, then you may need to make corresponding changes in your code. This table summarizes the changes:
73+
74+
Scope | Type of change | Detail
75+
--- | --- | ---
76+
`ILicenseInformationFetcher.FetchLicenseInformationAsync` | New parameter | `int timeoutInSeconds`
77+
`ILicenseInformationFetcher.AppendLicensesToDictionary` | Generic Type | `IDictionary` instead of `Dictionary` for `partialLicenseDictionary`
78+
`ILicenseInformationFetcher.ConvertClearlyDefinedApiResposeToList` | Generic Type | Returns `IDictionary` instead of `Dictionary`
79+
`ILicenseInformationFetcher.ConvertComponentsToListForApi` | Generic Type | Returns `IList` instead of `List`
80+
`ILicenseInformationFetcher.FetchLicenseInformationAsync` | Generic Type | Returns `IList` instead of `List`
81+
`ILicenseInformationService.FetchLicenseInformationFromAPI` | New parameter | `int timeoutInSeconds`
82+
`ILicenseInformationService.FetchLicenseInformationFromAPI` | Generic Type | `IList` instead of `List` for `listofComponetsForApi`
83+
`ILicenseInformationService.FetchLicenseInformationFromAPI` | Generic Type | Returns `IList` instead of `List`
84+
`IRecorder` | New method | `void AddResult(string propertyName, string propertyValue)`
85+
`IAssemblyConfig` | New property | `ManifestInfo DefaultManifestInfoForGenerationAction`
86+
`IJsonArrayGenerator.GenerateAsync` | Generic Type | `IList` instead of `List` for `listOfComponenentsForApi`
87+
`IJsonArrayGenerator.GenerateAsync` | Generic Type | Returns `IList` instead of `List`
88+
`IMetadataBuilder` | New method | `TryGetCreationInfoJson(IInternalMetadataProvider internalMetadataProvider, out GeneratorResult generatorResult)`
89+
`IManifestToolJsonSerializer` | New method | `void Write(JsonElement jsonElement)`
90+
`ISignedValidator.Validate` | New parameter | `IDictionary<string, string> additionalTelemetry`
91+
`ISbomParser.GetMetadata()` | Return type | `SpdxMetadata` instead of `Spdx22Metadata`
92+
`ISbomParser` | New method | `void EnforceConformanceStandard(ConformanceStandardType conformanceStandard)`
93+
`IConfiguration` | New property | `ConfigurationSetting<ConformanceStandardType> ConformanceStandard`
94+
`IConfiguration` | New property | `ConfigurationSetting<int> LicenseInformationTimeoutInSeconds`
95+
96+
97+

‎docs/sbom-tool-api-reference.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
Users can use the C#-based SBOM API for calling the SBOM tool. This guide is intended to assist users in integrating the SBOM tool API package in a .NET project.
44

5+
## Migration notes
6+
7+
If you are migrating from version 3 of the API, please refer to the [API Version 4 migration guide](./api-version-4-migration-guide.md) for changes you may need to make in your code
8+
59
## Prerequisites
610

711
* A .NET project that can ingest packages from nuget.org.

0 commit comments

Comments
 (0)