API Design - two step resource creation

Question

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).

Answer 1

Excuse me in advance for neglecting a key factor in this question. API JSON is a specification.

In the first place, JSON API implements HATEOAS which in my opinion, makes easier the answer to the question.

Attending your last comment, I have checked out the official website and, as I expected, JSON API and I are aligned with the solution you need. However, we differ in some points.

Step 1: Creating a new resource

Let consumers discover the new resource. This is essentially what HATEOAS suggests. If we do, consumers can follow the link and address further operations to the new URI.

For brevity, I will leave out the request and the response body.

Take a look at the example:

1.1. Request

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/and.api+json

1.2. Response

HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json

Note that, /photos and /users are equivalent. Look at the response headers. As I commented in my previous answer, the response SHOULD contain the header Location which contains the URL to the new resource. This is how we make new resources available after its creation.

Special attention to the specification, which states that, according with the state of the resource on the server-side, we should respond with one or another code.

You might be interested in responses 202 Accepted if the resource in the remote API (the one you are proxying) is not created at the moment of the request. For example, when the remote resource is created anytime in the future. Check out the 3rd API documentation. It's important for you to know what's the state of the remote resource after the POST request.

1.3. The identifier

You have commented that you have a way to marry both steps. It does mean that you have a way to identify the remote resource in the remote API. Fine. You have to make available such mechanisms. Maybe with a deferred id or maybe using the remote resource identifier. Whatever you choose, you make it available to the rest through the resultant URI (/users/1).

2. Updating resources

Here is where JSON API and I differ. JSON API advocates for PATCH requests. I'm not a fan of PATCH (probably because I'm reluctant to send chunks of my data model). Nevertheless, both assume that the resource already exists (step 1).

Look at the example.

2.1. Request

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

As for creation, the response status code will depend on the state of the resource on the server-side. You will have to decide in every case which one to use.

Summing up

Essentially, the resource creation in two steps can be translated into:

• Step 1: Create (POST /users)
• Step 2: Update (PATCH /users/here_your_identifier)