...
| Name | Company | Phone Number | Time Zone | |
|---|---|---|---|---|
| AT&T | dw2049@att.com | (561) 371-7619 | EST | |
| AMDOCS | sharon.chisholm@amdocs.com | EST | ||
| Huawei | Christopher.Donley@huawei.com | |||
| AT&T | gg2147@att.com | (847) 420-8459 | ||
| Mark Ho | AT&T | mh574f@att.com | (781) 791-4345 | EST |
| VMware | ramkik@vmware.com | |||
| AT&T | am803u@att.com | EST | ||
| ARM (OAM) | adolfo.perez-duran@oamtechnologies.com | 720.560.2659 | MT | |
| Intel | alex.vul@intel.com | |||
| Huawei | Parviz.Yegani@huawei.com | (408) 759-1973 | PT |
...
- API-wide - versioning at this level creates a new set of URIs to identify the resources
- Resource-wide - independently version different parts of the API's resource model; major change to a specific resource model with the notion that not all the resource models will change (namespace changes, add a new resource)
- Representation layer - modify and enhance the format, structure or content of resources that are served by the API without changing the resource model
- Behavior change - changes in behavior that do not change the resource model or representation; can include changes in process or state management
Use Case | Layer | MAJOR | MINOR | PATCH1 |
|---|---|---|---|---|
Refactoring resource model, if it has become fragile or overly complex through many evolutionary steps; introduce a set of namespaces to reflect the category of resources (nothing is where it used to be) | API | X | ||
| Restructure resource(s) to meet new business requirements/conform to emerging interface standard(s) | API | X | ||
| Add a required request parameter value without default | API | X | ||
| Add a required request parameter value with default | API | X | ||
| Add a new resource model or type | Resource | X | ||
| Update an existing resource model or type w/BWC | Resource | X | ||
| Update an existing resource model or type w/out BWC | Resource | X | ||
| Adding optional data items to an input resource representation | Resource | X | ||
| Add a new behavior method w/no changes to existing behavior methods (e.g. add PUT as a method when it did not exist as prior functionality) | Behavior | X | ||
| Changes to data volume on returned response | Behavior | X | ||
| Changes to undocumented sorting order of data on returned response w/out changes to volume | Behavior | X | ||
| Changes to documented sorting order of data on returned response w/out changes to volume | Behavior | X | ||
| Changes in behavior that do not change the resource model or representation | Behavior | X | ||
| Deprecate method, but do not change the structure of the resource model or representation | Behavior | X | ||
Adding new optional parameter(s) (that do not change default behavior) to requests | Representation | X | ||
Adding data items to an output resource representation, where any prescribed schema validation (for example, XML Schema or JSON-Schema validation) is not broken | Representation | X | ||
| Fix a defect that does not impact behavior or representation (e.g. fix internal algorithm to run more efficiently) | General | X | ||
| Changes to error codes, whereas the error code content is updated or changed, with no change in the resource model or representation | API | X |
1 PATCH refers to the position in the version number, not the HTTP method of PATCH. This method should not be used as it is idempotent.
Requirements/Extensions of the Swagger Specification
Spec ID | Specification/RequirementSpe |
|---|---|
| SG-1 | All components shall use Swagger 2.0. The specification may be found here. OpenAPI 3.0 is a roadmap item. |
| SG-2 | Within the Info Object, the following annotations are included in the Swagger specification and shall be required, even if they are optional in the Swagger spec: title description version - fully-qualified version number of the Swagger file (ex: 1.4.18) |
| SG-3 | Within the Info Object, the following are extensions of the Swagger specification and shall be required: x-planned-retirement-date - use YYMM; string type. This is the date that the API shall be deprecated, based on the BWC Policy. NOTE: APIs may be active after their retirement date, but are not guaranteed to remain in production. An API retirement may be pushed out to accommodate BWC for clients. x-component - SDC, MSO, SNIRO, etc., or the mS name; string type. This is the component that owns the API. |
| SG-4 | Under the Path, the following shall be required: x-interface info - this contains two attributes:
|
| SG-5 | Swagger files shall be generated at build time, and be placed in a centralized CodeCloud repository located at: TBD |
| SG-6 | Within the Path Item Object, the following are included in the Swagger specification and shall be required: description - string parameters
|
Next Working Team Call
- Dana Bobko will setup for week of 4/9/2018.
...