Sean Clark Hess Sean Clark Hess - 26 days ago 8
reST (reStructuredText) Question

How to model data for a JSON API and a Document Database

I am making a simple REST API in front of a NoSQL database that stores records as documents similar to JSON (but not exactly the same). Each record has some fields, including

id
for the database, and also including some derived fields, like
dateCreated
.

Any time I GET anything, I want to return the objects with all the fields.

// GET /users returns an array of these in JSON
// [{id:"xxx", name:"Bobby", dateCreated:"YYYY-MM-DD"]
data User = User { id :: String, name :: String, dateCreated :: XXX }


But any time I POST or PUT anything, they client should send an object with the
id
field and any derived fields missing. The database is responsible to create the id when I save it, and I would create some derived fields

// POST /users would need you to post only the name.
// {name:"Henry"}
data PartialUser = PartialUser { name :: String }


If resource represents objects of type
User
, what should I call the thing client is sending to me? Would you make all the derived fields
Maybe
values? Or would you create a second object called
PostedUser
or something?

Answer Source

It can be many things:

  • a request body
  • the representation of the intended resource state of the client
  • a command DTO which you can send to the domain logic in order to process it by CQRS

I would make it CreateUser command, but if you don't want to use CQRS and DDD, then you would probably call it as PartialUserRepresentation, or you don't create a data structure, just use the properties to create a new User entity. Ofc. if you use entities.

So I would say it depends on the architecture of your system.