From d685a362766bcb2706cacd1c218d7d1b09695f1e Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Fri, 12 Jan 2024 14:14:10 +0000 Subject: [PATCH 1/7] ci: Add linting for Markdown files Adds linting using markdown lint for ADRs and the README --- .github/workflows/ci-workflow.yml | 6 ++++-- .markdownlint-cli2.yaml | 22 ++++++++++++++++++++++ Makefile | 11 +++++++++++ README.md | 9 +++++++-- 4 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 .markdownlint-cli2.yaml diff --git a/.github/workflows/ci-workflow.yml b/.github/workflows/ci-workflow.yml index 3c64b49..8423b09 100644 --- a/.github/workflows/ci-workflow.yml +++ b/.github/workflows/ci-workflow.yml @@ -30,9 +30,11 @@ jobs: with: fetch-depth: 0 # check out the entire repo history for SHA verification in lastSuccessful step + - name: Lint Markdown docs + run: make lint-markdown + - name: Lint specification - run: make lint - working-directory: ./api + run: make lint-apispec - name: Render API docs run: make render diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..6930ea7 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,22 @@ +--- +globs: + - '**/*.md' + +ignores: + - 'LICENCE.md' + - 'ICLA.md' + - '.github/' + +default: true + +config: + default: true + + # Allow arbitrary line length + MD013: false + + # Allow duplicate headings + MD024: false + +customRules: + - markdownlint-rule-max-one-sentence-per-line # Enforce one-sentence-per-line using custom rule diff --git a/Makefile b/Makefile index d11a6e8..0ebb835 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,5 @@ +NUM_OF_PARENT:=$(shell echo $$(( $(words $(MAKEFILE_LIST)))) ) +topdir:=$(realpath $(dir $(word $(NUM_OF_PARENT),$(MAKEFILE_LIST)))) all: help @@ -10,10 +12,19 @@ mock-server-up: mock-server-down: $(MAKE) -C api/ $@ +lint-markdown: + docker run -v ${topdir}:/workdir davidanson/markdownlint-cli2-rules:v0.12.1 + +lint-apispec: + $(MAKE) -C api/ lint + +lint: lint-markdown lint-apispec + help: @echo "tams-api" @echo "make render - Generate HTML rendered version of OpenAPI document" @echo "make mock-server-up - Start a mock API server on http://localhost:4010" @echo "make mock-server-down - Stop the mock API server" + @echo "make lint - Lint API specification document and Markdown files" .PHONY: help render mock-server-up mock-server-down diff --git a/README.md b/README.md index 815f2b0..2abc7f8 100644 --- a/README.md +++ b/README.md @@ -66,10 +66,15 @@ Flows in the store are assumed to be immutable: once a grain has been written to When it becomes necessary to mutate content, for example reversioning content or performing production operations, the Flow ID (and potentially Source ID) will change. Various scenarios are explored in the [Practical Guidance for Media](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/3.0._Practical_Guidance_for_Media.html) section of AMWA MS-04. ### API Versioning -The API is versioned using a major and minor version number. A breaking change results in a major version increment and the minor version is reset to 0. Features such new endpoints or new (optional) data properties result in a minor version increment. Other changes such as bug fixes and documentation changes do not result in version updates. Note that the version may change frequently whilst the API is still under development! + +The API is versioned using a major and minor version number. +A breaking change results in a major version increment and the minor version is reset to 0. +Features such new endpoints or new (optional) data properties result in a minor version increment. +Other changes such as bug fixes and documentation changes do not result in version updates. +Note that the version may change frequently whilst the API is still under development! ## Proposals, Decisions and Architecture Changes -This repository uses [(M)ADR documents](https://adr.github.io/madr/) to propose significant changes, facilitate discussions and decision making, and to store a record of options that were considered. +This repository uses [(M)ADR documents](https://adr.github.io/madr/) to propose significant changes, facilitate discussions and decision making, and to store a record of options that were considered. These documents may be found in the [docs/adr/decisions](./docs/adr/decisions/) directory, and are managed as described by the [ADR Readme](./docs/adr/decisions/README.md). ## Get in touch From 48a9f030213fce58044e0d62df0d809cb3d72342 Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Fri, 12 Jan 2024 14:14:33 +0000 Subject: [PATCH 2/7] Fix linting for Markdown files --- CONTRIBUTING.md | 16 ++++++-- README.md | 38 +++++++++++++++---- ...arkdown-adrs-to-record-design-decisions.md | 6 +-- docs/adr/decisions/README.md | 12 ++++-- docs/adr/template/adr-template.md | 2 +- 5 files changed, 55 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 637a88b..d096fc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,19 +1,27 @@ # Contributing -Thank you for your interest in our work. If you're more generally interested in our Time Addressable Media Stores work, the implementations we've built internally or opportunities for collaboration, please reach out to us at + +Thank you for your interest in our work. +If you're more generally interested in our Time Addressable Media Stores work, the implementations we've built internally or opportunities for collaboration, please reach out to us at ## API Improvements -We welcome suggestions for changes and improvements to the API. Feel free to reach out using the email address above, or alternatively open a GitHub Issue. + +We welcome suggestions for changes and improvements to the API. +Feel free to reach out using the email address above, or alternatively open a GitHub Issue. ## Submitting Changes -If you've fixed a problem or thought of an improvement, feel free to fork the repository and submit a Pull Request in the usual way. The process is: + +If you've fixed a problem or thought of an improvement, feel free to fork the repository and submit a Pull Request in the usual way. +The process is: 1. Fork the repository 2. For more significant changes, consider starting with writing an ADR document: see [the ADR readme](./docs/adr/decisions/README.md) for more 3. Make, commit and push changes to a branch on your fork (make sure the commit message contains your email address) 4. If you haven't already done so, sign the CLA (see below) -5. Open a Pull Request with your changes. Don't worry about leaving empty spaces on the PR template (it's aimed at internal contributions), just fill in the description +5. Open a Pull Request with your changes. + Don't worry about leaving empty spaces on the PR template (it's aimed at internal contributions), just fill in the description ## Contributor Licence Agreement (CLA) + We desire that contributors of pull requests have signed, and submitted by email, an [Individual Contributor Licence Agreement (ICLA)](./ICLA.md), which is based on the Apache CLA. The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to the BBC and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time. diff --git a/README.md b/README.md index 2abc7f8..d73fb58 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Time-addressable Media Store API + This repository contains API definitions for a Time-addressable Media Store (TAMS) server, which can be used to store, query and access segmented media - distinct from files and streams, but sharing characteristics of both. BBC R&D have demonstrated use of the TAMS approach as part of composable, software-defined workflows which can run in the cloud, on-premise or in a hybrid environment. @@ -26,33 +27,48 @@ Media can be moved between locations and storage tiers as needed. Users of TAMS are insulated from the details of the underlying storage. ## Documentation + - OpenAPI Specification: [TimeAddressableMediaStore.yaml](./api/TimeAddressableMediaStore.yaml) - Rendered Documentation: [https://bbc.github.io/tams](https://bbc.github.io/tams) -This repo contains some automation to run a mock version of the API using [Stoplight Prism](https://stoplight.io/open-source/prism). To run the mock server using Docker, try something like the command below (or run `make mock-server-up`): -``` +This repo contains some automation to run a mock version of the API using [Stoplight Prism](https://stoplight.io/open-source/prism). +To run the mock server using Docker, try something like the command below (or run `make mock-server-up`): + +```shell docker run --rm --init --name mock-tams -v "$(pwd)":/data:ro -p 4010:4010 stoplight/prism mock /data/TimeAddressableMediaStore.yaml -h 0.0.0.0 ``` A mock API server will start at ## Design -The store handles Flows which exist on an infinite timeline, are immutable, and can be grouped by Sources (based on the Flows and Sources in the [AMWA NMOS MS-04 model](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/2.1._Summary_and_Definitions.html)). A flow ID and timerange refers to a sequence of grains (_e.g._ frames of video or set of audio samples) and any point in a Flow can be uniquely addressed by a `` tuple. This unique address is guaranteed to refer to a specific frame, or set of audio samples, so it can be safely passed around other tools or programs. At any time the unique address can be exchanged for the media data by an API call. But if that is not needed, media work can be done purely by reference. -Grains are grouped into Flow Segments, containing for example one second of content, wrapped in a container format such as MPEG-TS. The store provides a mechanism to upload and register new segments, and an interface to request all the segments covering a particular timerange and their download URLs; an approach inspired by chunked streaming protocols like HTTP Live Streaming. +The store handles Flows which exist on an infinite timeline, are immutable, and can be grouped by Sources (based on the Flows and Sources in the [AMWA NMOS MS-04 model](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/2.1._Summary_and_Definitions.html)). +A flow ID and timerange refers to a sequence of grains (_e.g._ frames of video or set of audio samples) and any point in a Flow can be uniquely addressed by a `` tuple. +This unique address is guaranteed to refer to a specific frame, or set of audio samples, so it can be safely passed around other tools or programs. +At any time the unique address can be exchanged for the media data by an API call. +But if that is not needed, media work can be done purely by reference. + +Grains are grouped into Flow Segments, containing for example one second of content, wrapped in a container format such as MPEG-TS. +The store provides a mechanism to upload and register new segments, and an interface to request all the segments covering a particular timerange and their download URLs; an approach inspired by chunked streaming protocols like HTTP Live Streaming. -Segments may be stored separately from the metadata linking them to a position on the timeline, separating the metadata and data planes. For example our implementation uses an object store (_e.g._ AWS S3) for the segments, passing S3 URLs to the client to upload directly and taking advantage of the scalability of cloud object storage. Segments are also de-coupled from their point in the timeline by a link between their `` tuple and the underlying object ID, so a single segment can appear at multiple points in multiple flows. This allows for copy-on-write semantics: immutability means a new Flow must be created to make changes to existing parts of the timeline, but for unmodified portions of the timeline the new `` tuple points to the existing object ID. +Segments may be stored separately from the metadata linking them to a position on the timeline, separating the metadata and data planes. +For example our implementation uses an object store (_e.g._ AWS S3) for the segments, passing S3 URLs to the client to upload directly and taking advantage of the scalability of cloud object storage. +Segments are also de-coupled from their point in the timeline by a link between their `` tuple and the underlying object ID, so a single segment can appear at multiple points in multiple flows. +This allows for copy-on-write semantics: immutability means a new Flow must be created to make changes to existing parts of the timeline, but for unmodified portions of the timeline the new `` tuple points to the existing object ID. The Flow model is aligned with the principles and schemas of [AMWA NMOS IS-04](https://specs.amwa.tv/is-04/releases/v1.3.2/APIs/schemas/) to facilitate easy integration of NMOS-compliant media devices. ### Reading and Writing in the Store + The process of reading from the store is: + 1. Client identifies the Flow ID and timerange of interest 2. Client makes a request to [`GET flows//segments?timerange=`](https://bbc.github.io/tams/#/operations/GET_flows-flowId-segments) and receives a list of segments, timeranges and download URLs 3. Client downloads each URL, concatenates the segments together and unwraps the grains within 4. The first and last Flow Segment may contain more grains than requested, so the client should skip any received not in the requested timerange The process of writing to the store is: + 1. Client creates a Flow if necessary by making a request to [`PUT flows/`](https://bbc.github.io/tams/#/operations/PUT_flows-flowId) 2. Client makes a request to [`POST flows//storage`](https://bbc.github.io/tams/#/operations/POST_flows-flowId-storage) with the timerange to be written 3. Store responds with a list of segment timeranges and URLs to PUT segments to, along with an optional `pre` URL to call before writing @@ -61,9 +77,12 @@ The process of writing to the store is: 6. Client makes requests to [`POST flows//segments`](https://bbc.github.io/tams/#/operations/POST_flows-flowId-segments) with details of each new segment created, to register them on the timeline ### Flows, Sources and Mutation -Flows in the store are assumed to be immutable: once a grain has been written to a point on the timeline on a specific Flow, it cannot be changed. However Flows can always be extended, with empty spaces on the timeline filled in, and areas of the timeline can be permanently erased. -When it becomes necessary to mutate content, for example reversioning content or performing production operations, the Flow ID (and potentially Source ID) will change. Various scenarios are explored in the [Practical Guidance for Media](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/3.0._Practical_Guidance_for_Media.html) section of AMWA MS-04. +Flows in the store are assumed to be immutable: once a grain has been written to a point on the timeline on a specific Flow, it cannot be changed. +However Flows can always be extended, with empty spaces on the timeline filled in, and areas of the timeline can be permanently erased. + +When it becomes necessary to mutate content, for example reversioning content or performing production operations, the Flow ID (and potentially Source ID) will change. +Various scenarios are explored in the [Practical Guidance for Media](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/3.0._Practical_Guidance_for_Media.html) section of AMWA MS-04. ### API Versioning @@ -74,8 +93,11 @@ Other changes such as bug fixes and documentation changes do not result in versi Note that the version may change frequently whilst the API is still under development! ## Proposals, Decisions and Architecture Changes + This repository uses [(M)ADR documents](https://adr.github.io/madr/) to propose significant changes, facilitate discussions and decision making, and to store a record of options that were considered. These documents may be found in the [docs/adr/decisions](./docs/adr/decisions/) directory, and are managed as described by the [ADR Readme](./docs/adr/decisions/README.md). ## Get in touch -If you'd like to know more about our work on TAMS, talk about our implementations or start a collaboration, contact us on . Also see [CONTRIBUTING.md](./CONTRIBUTING.md) for more about how to make contributions. + +If you'd like to know more about our work on TAMS, talk about our implementations or start a collaboration, contact us on . +Also see [CONTRIBUTING.md](./CONTRIBUTING.md) for more about how to make contributions. diff --git a/docs/adr/decisions/0000-use-markdown-adrs-to-record-design-decisions.md b/docs/adr/decisions/0000-use-markdown-adrs-to-record-design-decisions.md index 6346e5c..9415d4b 100644 --- a/docs/adr/decisions/0000-use-markdown-adrs-to-record-design-decisions.md +++ b/docs/adr/decisions/0000-use-markdown-adrs-to-record-design-decisions.md @@ -25,7 +25,8 @@ It's also beneficial to anyone involved in the collaborative development of the ## Decision Outcome Chosen option: "Use (M)ADR documents, one per decision", because -Meets all of the requirements. Could be supplemented with use of Issues and/or Discussions if/when the need arises, but these serve slightly different purposes. +Meets all of the requirements. +Could be supplemented with use of Issues and/or Discussions if/when the need arises, but these serve slightly different purposes. ### Consequences @@ -35,7 +36,7 @@ Meets all of the requirements. Could be supplemented with use of Issues and/or D ### Implementation -Implemented by https://github.com/bbc/tams/pull/15/ +Implemented by ## Pros and Cons of the Alternative Options @@ -50,4 +51,3 @@ It was felt that GitHub Discussions, whilst a potentially useful adjunct to ADRs ### Use some combination of the considered options This will be kept under review, and other mechanisms may be introduced to support the use of ADRs - diff --git a/docs/adr/decisions/README.md b/docs/adr/decisions/README.md index 6db4125..5e14b8b 100644 --- a/docs/adr/decisions/README.md +++ b/docs/adr/decisions/README.md @@ -4,21 +4,24 @@ This directory contains decision records for the TAMS API, describing the ration They exist to describe proposals, to facilitate discussions and decision making, and to serve as a concise record of those discussions. The full list is located as Markdown files [in this directory](./). -These records are based on the Markdown Any Decision Record template - see https://github.com/adr/madr for the original template, and for more on ADRs in general. +These records are based on the Markdown Any Decision Record template - see for the original template, and for more on ADRs in general. ADRs will be submitted using GitHub PRs, which provides necessary tooling for community review and approval. Not all changes to the API definition will warrant an ADR. One of the tests that will need to be applied on review of PRs containing ADR docs, and PRs that don't, is that of architectural significance. ## Creating a new ADR + 0. Look at the existing list of ADRs, and see if this has been considered before, or whether it would supersede any of them 1. Copy the [adr-template.md](../template/adr-template.md) into this directory 2. Name it with the next number in sequence, and a sensible title (e.g. `00023-improve-source-hierarchy.md`) -3. Fill in the template: at least the "Context", "Considered Options" and "Pros and Cons..." sections. Feel free to choose a preferred option and add it to the "Decision Outcome" section as well. +3. Fill in the template: at least the "Context", "Considered Options" and "Pros and Cons..." sections. + Feel free to choose a preferred option and add it to the "Decision Outcome" section as well. 4. If making the proposed changes (e.g. to the API, schemas or examples) helps to explain your proposal, make those changes as well 5. Open a PR with your MADR document and any other changes ## Reviewing the proposal + During the review process, use PR comments to ask questions, make suggestions or generally discuss the proposal. Alternatively, if a synchronous discussion takes place (e.g. an in-person or online meeting), add a description of what was discussed and the outcome into the ADR document itself. @@ -26,10 +29,13 @@ Generally PRs should remain open for review for a period of time to invite comme The maintainers at BBC R&D will facilitate this process, and expedite it if necessary ## Finishing and merging + Once the review process has completed and a consensus has been reached: + 1. Amend the ADR document with relevant points from the review discussion, and changes to the decision if necessary 2. Try to make these changes with new commits, so it's possible to see the original version in the Git history -3. If you added an implementation at the same time, make the required changes there too. Rememeber to bump the API version in accordance with [the README](../../../README.md#api-versioning) +3. If you added an implementation at the same time, make the required changes there too. + Rememeber to bump the API version in accordance with [the README](../../../README.md#api-versioning) 4. Amend the ADR status to "accepted" 5. Consider whether your rework would benefit from someone else looking over it 6. Merge the PR diff --git a/docs/adr/template/adr-template.md b/docs/adr/template/adr-template.md index e461e66..b2df448 100644 --- a/docs/adr/template/adr-template.md +++ b/docs/adr/template/adr-template.md @@ -25,7 +25,7 @@ status: "{proposed | rejected | accepted | deprecated | … | superseded by [ADR ## Decision Outcome Chosen option: "{title of option 1}", because -{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. +{Justification, e.g., only option which resolves requirements, or comes out best (see below)}. ### Consequences From 3c3703d4ac41b9d9f74662b011a911fcab6c5223 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Wed, 10 Jan 2024 10:30:55 +0000 Subject: [PATCH 3/7] Add `modified_by` field --- api/examples/flow-get-200-audio-aac.json | 1 + api/examples/flow-get-200-video-h264.json | 1 + api/examples/flow-get-200-video-raw.json | 1 + api/examples/flows-get-200.json | 3 +++ api/schemas/flow-core.json | 6 +++++- 5 files changed, 11 insertions(+), 1 deletion(-) diff --git a/api/examples/flow-get-200-audio-aac.json b/api/examples/flow-get-200-audio-aac.json index 020aeb5..05ef046 100644 --- a/api/examples/flow-get-200-audio-aac.json +++ b/api/examples/flow-get-200-audio-aac.json @@ -9,6 +9,7 @@ "label": "capture_1", "format": "urn:x-nmos:format:audio", "created_by": "tams-dev", + "modified_by": "tams-dev", "tags": { "quality": "web", "_tams_segmentation_rate": "375/8" diff --git a/api/examples/flow-get-200-video-h264.json b/api/examples/flow-get-200-video-h264.json index 16272ce..9d37f67 100644 --- a/api/examples/flow-get-200-video-h264.json +++ b/api/examples/flow-get-200-video-h264.json @@ -9,6 +9,7 @@ "label": "bbb", "format": "urn:x-nmos:format:video", "created_by": "tams-dev", + "modified_by": "tams-dev", "tags": { "quality": "full", "_tams_segmentation_rate": "10" diff --git a/api/examples/flow-get-200-video-raw.json b/api/examples/flow-get-200-video-raw.json index 342c3a8..bd842ef 100644 --- a/api/examples/flow-get-200-video-raw.json +++ b/api/examples/flow-get-200-video-raw.json @@ -9,6 +9,7 @@ "label": "capture_1", "format": "urn:x-nmos:format:video", "created_by": "tams-dev", + "modified_by": "tams-dev", "tags": { "quality": "full", "_tams_segmentation_rate": "25" diff --git a/api/examples/flows-get-200.json b/api/examples/flows-get-200.json index 8a029a7..71e0712 100644 --- a/api/examples/flows-get-200.json +++ b/api/examples/flows-get-200.json @@ -10,6 +10,7 @@ "label": "bbb", "format": "urn:x-nmos:format:video", "created_by": "tams-dev", + "modified_by": "tams-dev", "tags": { "quality": "full", "_tams_segmentation_rate": "10" @@ -53,6 +54,7 @@ "label": "capture_1", "format": "urn:x-nmos:format:audio", "created_by": "tams-dev", + "modified_by": "tams-dev", "tags": { "quality": "web", "_tams_segmentation_rate": "375/8" @@ -77,6 +79,7 @@ "label": "capture_1", "format": "urn:x-nmos:format:video", "created_by": "tams-dev", + "modified_by": "tams-dev", "tags": { "quality": "full", "_tams_segmentation_rate": "25" diff --git a/api/schemas/flow-core.json b/api/schemas/flow-core.json index e8fb382..8d20168 100644 --- a/api/schemas/flow-core.json +++ b/api/schemas/flow-core.json @@ -28,7 +28,11 @@ "type": "string" }, "created_by": { - "description": "A string identifier for the entity that created the flow", + "description": "A string identifier for the entity that created the flow. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.", + "type": "string" + }, + "modified_by": { + "description": "A string identifier for the entity that modified the flow metadata most recently. Implementations SHOULD set suitable default values for `modified_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.", "type": "string" }, "tags": { From cddf7ba81b835ea474f1c208a1375c91517d774b Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 11 Jan 2024 15:27:28 +0000 Subject: [PATCH 4/7] Add `created_by` field to deletion requests --- api/examples/deletion-request-get-200.json | 1 + api/examples/deletion-requests-get-200.json | 3 +++ api/schemas/deletion-request.json | 4 ++++ 3 files changed, 8 insertions(+) diff --git a/api/examples/deletion-request-get-200.json b/api/examples/deletion-request-get-200.json index d9f650d..58a4bce 100644 --- a/api/examples/deletion-request-get-200.json +++ b/api/examples/deletion-request-get-200.json @@ -7,5 +7,6 @@ "created": "2018-12-10T15:40:08.339376+00:00", "updated": "2018-12-10T15:40:09.339393+00:00", "expiry": "2018-12-11T15:40:09.339393+00:00", + "created_by": "tams-dev", "status": "started" } \ No newline at end of file diff --git a/api/examples/deletion-requests-get-200.json b/api/examples/deletion-requests-get-200.json index 3e09a6a..c67af57 100644 --- a/api/examples/deletion-requests-get-200.json +++ b/api/examples/deletion-requests-get-200.json @@ -8,6 +8,7 @@ "created": "2018-12-10T15:40:08.339376+00:00", "updated": "2018-12-10T15:40:09.339393+00:00", "expiry": "2018-12-11T15:40:09.339393+00:00", + "created_by": "tams-dev", "status": "started" }, { @@ -19,6 +20,7 @@ "created": "2018-12-10T15:40:08.339376+00:00", "updated": "2018-12-10T15:40:09.339393+00:00", "expiry": "2018-12-11T15:40:09.339393+00:00", + "created_by": "tams-dev", "status": "started" }, { @@ -30,6 +32,7 @@ "created": "2018-12-10T15:40:08.339376+00:00", "updated": "2018-12-10T15:18:52.426792+00:00", "expiry": "2018-12-11T15:40:09.339393+00:00", + "created_by": "tams-dev", "status": "error", "error": { "type": "TAMSError", diff --git a/api/schemas/deletion-request.json b/api/schemas/deletion-request.json index 9ba7eef..6c7b059 100644 --- a/api/schemas/deletion-request.json +++ b/api/schemas/deletion-request.json @@ -37,6 +37,10 @@ "type": "string", "format": "date-time" }, + "created_by": { + "description": "A string identifier for the entity that created the deletion request. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.", + "type": "string" + }, "updated": { "description": "Date/Time when this deletion request was updated", "type": "string", From 32089d6e932b730953770d902ecf5ade6f3c3083 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Wed, 17 Jan 2024 10:32:31 +0000 Subject: [PATCH 5/7] Add ADR --- .../0001-expand-created-modified-metadata.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/adr/decisions/0001-expand-created-modified-metadata.md diff --git a/docs/adr/decisions/0001-expand-created-modified-metadata.md b/docs/adr/decisions/0001-expand-created-modified-metadata.md new file mode 100644 index 0000000..3e6290c --- /dev/null +++ b/docs/adr/decisions/0001-expand-created-modified-metadata.md @@ -0,0 +1,45 @@ +--- +status: "proposed" +--- +# Expand Created-by and Modified-by Metadata + +## Context and Problem Statement + +The existing API definition provides a `created-by` metadata field in the flow metadata. +This field contains an identifier for the entity which originally created the flow. +A similar `created-by` field on flow deletion requests would be useful. +Additionally, a `modified-by` field in flow metadata to track the entity which most recently modified requests would also be useful. + +## Decision Drivers + +* It has been useful to track the entity which created flows, primarily as a debugging tool, and to query flows by the entity which created them +* Flows may be modified by entities other than the one that created the flow +* Debugging/querying of modifications of flows and creation of flow deletion requests is currently more difficult than debugging/querying creation of flows + +## Considered Options + +* Provide additional metadata fields within the TAMS API +* Only store this information in other systems (e.g. AAA systems), outside of the scope of TAMS + +## Decision Outcome + +Chosen option: "Provide additional metadata fields within the TAMS API", because +This has been identified as a highly useful capability which should be available in a minimal system (i.e. one where only a TAMS service is deployed) + +### Implementation + +Implemented by https://github.com/bbc/tams/pull/17 + +## Pros and Cons of the Options + +### Provide additional metadata fields within the TAMS API + +* Good, because it reduces the barrier to deploying a minimal TAMS service Vs. the alternative +* Neutral, because it doesn't prevent the use of AAA systems +* Bad, because it may result in duplication of metadata in AAA systems + +### Only store this information in other systems + +* Good, because other systems such as AAA systems often provide more granular/extensive metadata +* Bad, because other systems such as AAA systems can be relatively difficult/complicated to set up +* Bad, because it necessitates the use of a further service for a fundamental capability From 43b7271cdd80fed87ca22778d021aa26aaa04e9e Mon Sep 17 00:00:00 2001 From: James Sandford Date: Wed, 17 Jan 2024 11:40:49 +0000 Subject: [PATCH 6/7] ADR status updated to accepted --- docs/adr/decisions/0001-expand-created-modified-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/decisions/0001-expand-created-modified-metadata.md b/docs/adr/decisions/0001-expand-created-modified-metadata.md index 3e6290c..380cf71 100644 --- a/docs/adr/decisions/0001-expand-created-modified-metadata.md +++ b/docs/adr/decisions/0001-expand-created-modified-metadata.md @@ -1,5 +1,5 @@ --- -status: "proposed" +status: "accepted" --- # Expand Created-by and Modified-by Metadata From 2349edc6a014c2c44e0697f64be23c6df11e7d7a Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 18 Jan 2024 11:06:54 +0000 Subject: [PATCH 7/7] Fix linting --- docs/adr/decisions/0001-expand-created-modified-metadata.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adr/decisions/0001-expand-created-modified-metadata.md b/docs/adr/decisions/0001-expand-created-modified-metadata.md index 380cf71..93525ce 100644 --- a/docs/adr/decisions/0001-expand-created-modified-metadata.md +++ b/docs/adr/decisions/0001-expand-created-modified-metadata.md @@ -28,13 +28,13 @@ This has been identified as a highly useful capability which should be available ### Implementation -Implemented by https://github.com/bbc/tams/pull/17 +Implemented by [https://github.com/bbc/tams/pull/17](https://github.com/bbc/tams/pull/17) ## Pros and Cons of the Options ### Provide additional metadata fields within the TAMS API -* Good, because it reduces the barrier to deploying a minimal TAMS service Vs. the alternative +* Good, because it reduces the barrier to deploying a minimal TAMS service Vs the alternative * Neutral, because it doesn't prevent the use of AAA systems * Bad, because it may result in duplication of metadata in AAA systems