Reducing redundant endpoint definitions
Hey forum,
I have a design question concerning the best practise for the following scenario.
I have a bunch of endpoints defined in my OpenAPI specification, but actually double what really ought to be fully defined. These operations apply to specific entities (let's say songs for the sake of example). Each song has a unique database assigned numeric song_id, but also has a freeform unique text "reference" that the client assigns when adding the song to the database. When a request is made to an endpoint that uses a song_reference, the server translates the reference into a song_id and then performs the request. The song_reference endpoints are effectively just wrappers for the song_id endpoints.
I don't want to have to define two sets of operations for what's effectively the same endpoints under the hood.
I have reproduced a minimal below:
openapi: "3.0.1" info: title: "Some API" version: "0.1" paths: /songs/download/by_id/{song_id}: get: summary: "Download a song by ID." operationId: getSongDownloadById parameters: - name: song_id in: path explode: false required: true description: "ID of song to download." schema: $ref: "#/components/schemas/song_id" example: 1434 responses: 200: description: "Operation successful" content: application/octet-stream: schema: type: string format: binary example: "...file's raw binary data..." 304: description: "Not modified" 404: description: "Not found response."
# Redundant endpoint definition below which is exactly the same except expects song_reference. /songs/download/by_reference/{song_reference}: get: summary: "Download a song by reference." operationId: getSongDownloadByReference parameters: - name: song_reference in: path explode: false required: true description: "Reference of song to download." schema: $ref: "#/components/schemas/song_reference" example: "some_reference" responses: 200: description: "Operation successful" content: application/octet-stream: schema: type: string format: binary example: "...file's raw binary data..." 304: description: "Not modified" 404: description: "Not found response" components: schemas: song_id: type: "integer" description: "Database assigned unique song ID." song_reference: type: "string" description: "Similar to song ID, but assigned by client when song added to database. Unique."
My goal is of course to reduce redundancy in the specification. Suggestions?
It sounds like you need to do one of two things:
1) As part of your regulatory documentation submission, you have documented how to interpret the TestComplete logs to be able to match what the TC logs say to what the reg requirements are. Having worked in a regulatory environment before (pharmaceutical clinical trials), so long as there are documented policies, procedures, etc., to go along with the submitted documentation, the auditors are usually fine with that. If you can explain what is out put by the testing tool in language that co-incides with your reg requirements, they are happy.
2) You need to build into your automation solution a way of writing the output that displays as "3 tests". I've done this in the past using the Log.AppendFolder and Log.PopFolder methods to create sections in my log to outline the tests as they are executed. The reason why test complete shows things as "test items" is because, as the tool is designed, there is a great deal of flexibility as to what constitutes a "test". Is every Script function a test? Is every KeywordTest a test? Or is a test a combination of several keyword tests and/or script functions? Or is a test driven by an external data source which fires off different script functions which, themselves, don't constitute specific tests but are "building blocks" that create tests? In other words, how do you define "a test"? Whatever definition you use, you then need to write appropriate out-put code, either directly to TC's log or to some other source location (SQL, HTML, etc) that formats the output do match your definition of "test".