Representing Non-CRUD Actions in JSON API Payloads

1

Hi,

My question is similar to this thread, however, slightly different.

I’m working on a scheduling application where appointments can be explicitly started and ended (think check-in/check-out). Starting an appointment is partially an update to the appointment status (changing it from scheduled to in progress), but it also kicks off a number of other processes, such as email notifications.

For example, my start endpoint is accessed at the following URL:

PATCH /appointments/{id}/start

In addition to the id, I also pass lat and lon (the latitude/longitude of the check-in). lat and lon aren’t actually fields in my appointment table, rather I have a checkinCoordinates field that is computed based on those params and inserted as a PostGIS-compliant format.

In the spirit of keeping all of my requests/responses JSON API-compliant, I am wondering the proper way to represent something like this given that the fields aren’t part of the actual model?

My initial thought was something like this:

{
                "data": {
                    "type": "appointment",
                    "id": "1",
                    "attributes": {
                        "lat": 39.232,
                        "lon": -132.232
                    }
                  }
              }

All that said, in general, I believe I’m a little confused on how to represent non-CRUD actions like this in JSON API. Any advice or suggestions would be greatly appreciated!

Thanks,
James

2

Hi jdixon,

Maybe I can help you a bit.

Have you heard of HATEOAS? It stands for Hypermedia As The Engine Of Application State, hypermedia of course being links ( and that is what jsonapi does really well!). The main idea is that your entire application is a state machine and manipulating that state should happen by following links. So it is perfect that you use /appointments/{id}/start! But I would rather use a POST method as you are creating that resource, and your type shouldn’t be appointment, but maybe something along the lines of appointment-commencement.

Remember that resources aren’t models! A resource is a function that maps to a set of models, wether those models are database records or actual file system files, doesn’t matter, and so what your API accepts doesn’t have to map 1:1 to what you store in your database, and in-fact it probably shouldn’t as that defeats the purpose of having an API.

4 Likes
3

@A-Helberg - this was extremely helpful and definitely provides me with a better understanding of how to effectively use JSON API. I really appreciate you taking the time to answer my question!

Cheers,
James

4

@jdixon04 My pleasure!