Web API Design book I'm reading

This is a few years old, but it's a good overview of APIs and some good design patterns. There's a signup page.

Web API Design - Crafting Interfaces that Developers Love

It's good advice and easy reading, but there's what I consider an error in there. Over on page 26, they suggest that it's OK to make a request like "GET /foo/123?method=delete" that will delete the resource.

That's a bad pattern. It's better to perform the delete via a POST, with a method=delete parameter in it. Bots generally don't spider forms - and you can avoid them by not publishing any form to delete anything.

On page 30, they recommend supporting a partial response syntax with dots to find related records:

/owners/5678?fields=name,dogs.name

While I like this idea, a lot, the programming implications are kind of big, but they just put it in there as a single sentence. Now, instead of returning a link to the dog in the dogs field, you return a link and the name. Here are the potential JSONs:

With the .name:

{
  "id":5678, 
  "name":"John", 
  "dogs":[ 
    { "url":"http://api.example.com/dogs/123", "name":"Fido" },
    { "url":"http://api.example.com/dogs/124", "name":"Yeller" }
  ]
}

Without the .name, there are three possible return values.

First, just a link to a request for a list of dogs:

{
  "id":5678, 
  "name":"John", 
  "dogs":"http://api.example.com/owners/5678/dogs" 
}

That's not that useful, but maybe it's exactly what we want. Here's one with a list of dogs. This requires a JOIN on the database, or a second query to retrieve the list. So it'll be as slow as the query with the .name:

{
  "id":5678, 
  "name":"John", 
  "dogs":[ 
    "http://api.example.com/dogs/123", 
    "http://api.example.com/dogs/124" 
  ]
}

Ehhh... might as well turn the list into a list of objects, so the client code can be more generic:

{
  "id":5678, 
  "name":"John", 
  "dogs":[ 
    { "url":"http://api.example.com/dogs/123" },
    { "url":"http://api.example.com/dogs/124" }
  ]
}

My gut feeling on this is, if there's no dot, don't drill down. This saves computer resources. If there is a dot, you will drill down and return the additional fields. So the URL could become something like this:

/owners/5678?fields=name,dogs.name,dogs.photo

The programming to support this URL is a bit more work. It's also a potential way for attackers to take a tour of your data, so... you have to add some input validation.

The documentation to support this is also significant, and is a barrier to using the API. So, there should be a default "fields" value that would return a useful object, which includes not only the resource, but linked resources with metadata like names and thumbnail image urls. (Now, I don't do this. I am only making APIs for my own clients, so all the relevant related objects are returned.)