12

I'm designing a REST service and there's a need for a check to see if an address is correctly entered. What I'm thinking about is how you would design a REST interface for checking if an full street address is valid.

I have this /address service and I could for example do a POST /address/validation which returns a xml/json true or false, but it seems quite un-REST-ful to me.

Another way would be to do a GET /address?street=xxx&nr=xxx&zipcode=xxx (and a few more parameters) and return a 200 OK if correct or a 404 Not found if not correct, which may be more REST-ful?

I started doing option 1) but the more I'm thinking about it, option 2) with the GET feels better...

Ideas?

Johan Danforth
  • 4,469
  • 6
  • 37
  • 36

3 Answers3

10

From a RESTful perspective, you're really returning a new resource, call it AddressValidation, that will contain your true or false value. So one approach would be to do a POST to /addressvalidation?street=xxx etc. I'd be fine with returning the result as JSON or using status codes. I'm not sure 404 is appropriate though; you might want to look at this discussion of validation return status codes.

I have the same issue with the GET /address?street=xxx&nr=xxx&zipcode=xxx approach as you propose it. To me, if it returns 404, that means that the address is literally not found (i.e. doesn't exist in the database), rather than that it's invalid (e.g. the zipcode is an invalid format; there can't be any such address). Again, see the linked discussion; it seems like 400 is a more appropriate response.

Community
  • 1
  • 1
Jacob Mattison
  • 50,258
  • 9
  • 107
  • 126
  • Thanks Jacob. We're actually going to test 2 things here - both if the address is in the correct format, and after that we check to see if the address actually exists. These are, as you say, two different things and should return different codes/data. – Johan Danforth Apr 29 '11 at 08:36
7

How about?

GET /addressValidity?street=xxx&nr=xxx&zipcode=xxx
=> 
200 OK
Content-Type: text/plain

true
Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 2
    Thanks Darrel, it's simple and I like it. It falls outside our normal behaviour of always returning xml or json depeding on accept-headers though. – Johan Danforth Apr 29 '11 at 08:34
  • 6
    @Johan Obviously you can use any media type you like. Text/plain is just nice for returning simple scalar values. It is unfortunate that the current obsession for "xml or json" really loses out on some of the benefits that REST brings with the ability to use many different media-types. – Darrel Miller Apr 29 '11 at 11:18
  • 2
    You can return an object, such as `{ "result": true }` – John Henckel Jun 19 '17 at 20:23
  • 2
    @JohnHenckel Saying that you can return an "object" over HTTP isn't really sufficient because the definition of what an object is depends on either a programming language, platform or media type specification. What you have shown is a JSON representation that contains what JSON defines as an object. That you can return. It's overkill, but it will work. – Darrel Miller Jun 19 '17 at 21:43
  • @JohanDanforth You are permitted to return text/plain only if the client's accept header indicates it accepts this type. Otherwise you must return a 406 Not Acceptable status code. – Ian Goldby Feb 09 '23 at 09:41
-2

I feel doing POST and returning status codes (200 OK if correct or a 404 Not found if not correct) is more restful. Because you are not GETting something GET doesn't look appropriate. You are POSTing some information to server and it does some processing (validation) and returns some response.

Reddy
  • 8,737
  • 11
  • 55
  • 73
  • 1
    POST doesn't look any good for this if you ask me. The RFC states "The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line" – bluehallu Mar 18 '14 at 10:08
  • Get is better than POST in this case, because the operation is idempotent – John Henckel Jun 19 '17 at 20:23