0

I'm building a REST api and want to make sure to follow the best practices. I need to expose a method which will return a 'Document' entity by its 'Lot' number.

It is possible that for a specific 'Lot', there's no 'Document' entity found. Also, property 'LotId' is not the key for 'Document' entity, it has his own key called 'DocumentId. What url structure shoul I use:

http://myUrl/Lots/{lotId}/Documents

or

http://myUrl/Documents?lotId=123

As it is posible to have no 'Document' attqached to a 'Lot', I don't want to return a 404 NotFound if there's no document found, I would return a 200 Ok with null

  • sounds good to me – Ewan Jan 16 at 19:36
  • with the first one you have the problem of the lot not existing at all vs lot with no document – Ewan Jan 16 at 19:37
  • @Ewan I would make a validation to return a 404 NotFounf if the lotId provided is wrong. So both url's make sense to you ? – Nicolas Boisvert Jan 16 at 19:40
  • they are fine. im not keen on 404s myself, or plural resource names. quotes around the lotid are prob not hood – Ewan Jan 16 at 19:44
  • 1
    Your question talks about a single Document as though the mapping from lot:document is 1:0 or 1:1 but your url says documents plural implying there are potentially many documents per lot. Which is it? – Caius Jard Jan 19 at 7:29
1

I need to expose a method which will return a 'Document' entity by its 'Lot' number.

The methods are GET, POST, PUT, DELETE etc. The HTTP verbs. Stick to them and think of what you are doing as state transfer, rather than issuing a command to the server. When you GET a resource you transfer the servers current state of that resource to the client. When you PUT you do the reverse.

The URI of a resource is a unique identifier. It doesn't really matter if it is

http://myUrl/Lots/{lotId}/Documents

or

http://myUrl/Documents?lotId=123

but it is important that a URI only points to one resource (that is what makes the URI unique). I prefer the first version to the latter

As it is posible to have no 'Document' attqached to a 'Lot', I don't want to return a 404 NotFound if there's no document found, I would return a 200 Ok with null

You should return a 404. 200 means the state transfer was successful (from server to client via the GET command). But if no resource exists then this isn't the case. In REST there is no "not found" resource, you just return 404

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.