API question

foo.md

POST /feeds

{ "url": "<feedURL>" }

Description: Creates a feed from <feedUrl> by making a HTTP request to the feed URL and saving it to the database.

This operation will fail if (in order):

1. Feed URL is an invalid URI (validation error)
2. A feed already exists with the requested feed URL (must be unique: validation error)
3. Feed URL does not resolve to a host
4. The request to the feed URL returns a bad status code (e.g. 404)
5. The response is not a feed, but something else (e.g. a HTML page)
6. The response is a feed, but is missing a title (invalid feed: validation error(?))

Questions

For each of these potential failure areas, how should the API respond?

1. Obivously a client error and should return a 400
2. Obivously a client error and should return a 400
3. The client input was valid, so what status code should this return?
4. The client input was valid, so what status code should this return?
5. The client input was valid, so what status code should this return?
6. The client input was valid, so what status code should this return? Technically this is an error when validating the feed (the title is required).

2. should probably be 422 (http://httpstatus.es/422). The URL is syntactically OK, but not a valid business operation.
   3/4/5) ditto.

For these cases you can return a document explaining exactly what went wrong and how the client can fix it.

Sometimes it is also useful for the server to ignore duplicate requests. If you're just storing the POSTed feed you could just return the created resource instead of failing. It makes it easier on the client as they can just retry their POST requests if they had any kind of error.

Another alternative is to let the client post to /feeds/{uuid} and store the UUID with the feed on the server.