REST API design for web pages with wizards

Question

I have a web page with wizard format. The submission button to the API will be in the 4th step of wizard. However I want the data entered to be stored in database before moving to the next step in the wizard. I also want the REST API to be working for the pages having single tab.

So I designed the API to take a query parameter action = draft or submit. If action is draft, only certain fields are mandatory. If action is submit, all fields are mandatory. Validations in the service layer of REST API will be done based on the query parameter. Looks like I've to explicitly specify the if/else clauses in the documentation. Is this an acceptable form of RESTful design ? What would be best design with these requirements ?

Answer 1

Since you want to persist things on the server between wizard steps, it seems perfectly acceptable to consider each step as a separate resource. Something along these lines :

POST /wizard/123/step1
POST /wizard/123/step2
POST /wizard/123/step3

By including hypermedia links in the response, you can inform the client on what it can do after this step - go forward or back for intermediary steps, and nothing for the final step. You can see an example of it in Figure 5 here.

Answer 2

I had needed to do something similar some time ago, and the following describes what we end up with.

We have two tables, Item and UnfinishedItem. When the user fills in the data with the wizard, the data are stored in UnfinishedItem table. At each wizard step, the server validates the data entered during that step. When the user is finished with the wizard, the wizard renders a hidden/read-only form in a confirmation page that shows all data to be submitted. The user can review this page and go back to the relevant step to fix errors. Once the user are satisfied with their entries, the user clicks submit and the wizard then submits all data in the hidden/read only form fields to the API server. When the API server processes this request, it reruns all validations that it did during each step of the wizard, and performs additional validations that doesn't fit into the individual steps (e.g. global validations, expensive validations). After all validations are completed, the API server creates an entry in the Item table.

The advantages of two table approach:

• in the database, you can have tighter constraints on the Item table than the UnfinishedItem table; you don't have to have optional columns that will actually be required when the wizard is finished.

• Aggregate queries across the finished Items for reporting are easier as you don't have to remember to exclude the UnfinishedItems. In our case, we never needed to do aggregate queries between Item and UnfinishedItems, so this isn't a problem.

The disadvantage:

• It's prone to duplication of the validation logic. The web framework we used, Django, makes this a bit more bearable as we used model inheritance with a bit of meta magic to change the constraints that we need to be different in Item and UnfinishedItem. Django generates most of the database and form validation from the model, and we only need to hack in a few additional validations on top of it.

Other possibilities I've considered and why we didn't go with them:

• saving the data in cookies or local storage: user can't continue their submission from a different device or if they delete their browser history
• store the UnfinishedItem as unstructured data (e.g. JSON) on the database or secondary datastore: I'll have to define parsing logic and can't use Django's automatic model/form validation.
• do the per step validation on the client side: I'll have to duplicate the validation logic between Python/Django and JavaScript.

Answer 3

I've implemented this in a way similar to a mix of @guillauma31 and @Lie Ryan's solutions.

Here are the key concepts:

1. There is a 3 step wizard that may be partially persisted until complete.
2. Each step has it's own resource (eg.: /users/:id_user/profile/step_1, .../step_2, etc.)
3. On each step, the data and completition status can be retrieved through GET requests and persisted through PATCH requests.
4. Each resource has it's own validation rules to the entered data.
5. Each step returns a key that have to be used in the input of the next step to guarantee the sequence. Once used or a new one is generated, this token expires.
6. On the final step, we have all needed data on the database and a confirmation screen is displayed. This confirmation calls another resource to mark the data as complete (eg.: .../profile/confirm). This resource doesn't need to receive all data again. It only marks the data as correct and complete.
7. There is a scheduled routine that wipes this incomplete entries that have more than a few days.

The front-end guys have to take care of the tokens to get the back and forth flow of the wizard working.

The API is stateless and atomic.

To make a "one step wizard" work with this setup you would have to change some things, like removing the token flow or creating a resource to return tokens based on the type of wizard or even create a new resource only to fill this specific single step wizard (like PUT /users/:id_user/profile/).