When would someone use this?¶
If you're working in a company that is building lots of APIs and want your teams to build APIs that are consistent and follow standards, you could define an API Design System and use it as a way to communicate what people can and can't do. You'll want tooling that uses the API Design System document to automate audits.
How do you write a scenario?¶
Let's say we want to specify what status codes people can use for a
Consider the condition - is this requirement related to an HTTP method? For this example, it's the
GETrequest, which is
[http, request, method, get].
Consider the subject - when a condition is met, what will the requirement apply to? In the example above, the condition would be the
GETrequest and the subject would be the response status code. The standard identifier here would be
[http, response, status_code].
Consider the requirement level - is this a recommendation? Then use
should. Does this requirement allow something? Use
may. If it's a strict requirement, then
Consider the values - if the condition is a
GETrequest and the subject is the response status code, then a possible value in our example would be
It would look something like this.
# ... design_system: - when: [http, request, method, get] then: - subject: [http, response, status_code] level: may values: - "200" # and any other status codes we want to allow
What about more complex conditions?¶
We're keeping this simple for now. If you have a need for more complex conditions, please get in touch and let us know!