URI Templates

[honzajavorek]

Let's say I want to have a root home resource like this:

{
  "name": "Animals API",
  "profileUrl": "https://docs.....com"
}

Then let's say the API allows the client to can get information about particular cows in the system. However, there's no way to list all cows in the system (i.e. no /cows URL for listing). Does it make sense to use RFC6570 URI Templates to indicate that the URL is just a template?

{
  "name": "Animals API",
  "cowUrl": "/cows/{id}",
  "tigerUrl": "/tigers/{id}",
  "gorillaUrl": "/gorillas/{id}",
  "profileUrl": "https://docs.....com"
}

[smizell]

Quick question: are you asking if we should change the spec, or in general how to use URI templates in your API with the existing RESTful JSON spec?

For using URI templates with the existing spec, there are a few ways you can do this. Since RESTful JSON leans more toward domain-specific implementations, you are free to use URI templates and simply document where you use them. You would just say, "when you see cowUrl, it's a URI template, and here are the parameters."

However, if you'd prefer a more general-purpose approach, you can create a URI template profile. Profiles are used to extend the format while not changing it. In this case, you could add a rule for *UriTemplate to make cowUriTemplate work. This way you can tell the difference between resolvable links and templates programmatically without changing the semantics of RESTful JSON.

[honzajavorek]

I'm asking whether using the URI Templates is something RESTful JSON supports. It's more about best practices, me understanding the spec correctly, and real world usage. I don't think the spec needs to mention this explicitly.

You would just say, "when you see cowUrl, it's a URI template, and here are the parameters."

That's what I thought and just wanted to check whether I get it right 🙂 Thanks for pointing to the URI template profile as well, that's an interesting idea.

[smizell]

Good to hear! If you make a public URI template profile, let me know!