add non-normative examples of API

WICG / uuid

UUID V4

Other

63 stars 10 forks source link

add non-normative examples of API #7

Closed bcoe closed 3 years ago

bcoe commented 3 years ago

I think it would be worthwhile to add at least one non-normative example of the UUID API in action.

The kv-storage spec has some great examples we could use for inspiration.

ctavan commented 3 years ago

I agree.

Given the general-purpose kind of nature of UUIDs I find it pretty challenging to come up with something that is both specific enough to serve as a helpful example but still general enough as to account for the universal nature of UUIDs. I will put some more thought into it.

bcoe commented 3 years ago

Here's an example of how we would add an examples section:

  <section>
    <h2 id="examples">Examples</h2>
    <p><em>This section is non-normative.</em></p>
    <pre class="example" id="example-text-file" title="Generate unique name for download">
      const filename = `${crypto.randomUUID()}.txt`;
      // do something with wilename.
    </pre>
  </section>

Garbee commented 3 years ago

A few other example ideas:

Generate unique IDs for generated elements on web pages
In an object constructor use a provided ID or generate a new one with the UUID API
(Possibly fringe/bad use case. Or maybe too much detail outright for an example.) A developer would provide a UUID as a request header going to a server. This way the backend could mark a request as being carried out across a distributed system and ignore duplicated requests that accidentally hit multiple servers.