I'm developing an API that allows consumers to create a resource. For example, a "user" resource can somewhat be created via POST and this payload (trying to use JSON API, btw):
POST /users HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "users",
"attributes": {
"first_name": "John",
"last_name": "Doe"
}
}
}
I say somewhat created because the resource is actually being created on an external system (and my API acts as proxy).
To completely create the resource, my API needs to take the second step -- and this step relies on information that my API does not have access to. The API consumer will, at a later point, obtain this additional information (e.g. via an SMS). The API consumer then needs to call my API again with this additional information in order to complete the second step of the resource creation.
What should this secondary call to my API look like? It would still be a POST to /users
, right? Perhaps just replace the attributes
with the additional information (e.g. "sms_key": "SHy562NSkd"
)?
POST /users HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "users",
"attributes": {
"sms_key": "SHy562NSkd"
}
}
}
Note that the API can completely perform this secondary step without any knowledge of the first step, but the API does have a way to marry the second step with the first step (might be useful for returning results about the resource created).