Let's Build an API together - Part 11

Last Update: 03.01.2018. By Jens in API Series | APIs | Newsletter

Now that we have settled with a DB, it is time to define our model.

Right now we only a have a single task entity. However, when we start with a project like this, we should consider future milestones a bit. When we know certain extension will come, like adding users and more boards, it helps to have an idea how today’s design decision will make a refactoring/migration to the future version easier or harder. If you are not sure a planned extension will ever come, or it is too vague, move forward as it is not there. It’s probably a case of YAGNI way (you ain’t gonna need it).

In any case, follow the KISS principle (keep it simple stupid). Over-engineering aka making things more complicated than necessary is a common problem among us developers. Often it’s like the more experience you got then more you will fall into this trap. I’ve been guilty of that myself numerous times…

So, for now our model looks like:

@Entity
public class TaskModel {

    @Id
    @GeneratedValue(strategy=GenerationType.SEQUENCE)
    private Long id;

    @Column(length=2048)
    private String content;

    @Column(length=10)
    private String category;

    @Column(length=10)
    @Enumerated(EnumType.STRING)
    private Lane lane;
}

I decided to use DB generated ids as numbers and no use UUIDs. It’s dead simple and takes less space in the DB. We also don’t need a globally unique id.

The content field is limited to 2048 characters. I don’t think a task should be that long but let’s leave it some space.

The category is a free-form string as I don’t intend to use it in any server-side logic. It is mainly for the UI to color the task differently.

The lane is an enum with the values todo, doing and done. I also updated it accordingly in the RAML. If we ever allow the user to create their own lanes, it’s a candidate for refactoring. I also store the enum as a string in the database. It’s better to read when querying on the database and it is also more robust than relying on the order of the values inside the enum.