使用JSON表示和链接资源的JAX-RS RESTful API

Question

Sometimes it's confusing how I should link resources within a RESTful API, consider for example the entities:

Profile (Users can create business profiles with address, details, etc..)

Plan (Already persisted in app's DB, created by administrators)

The request to create a Profile looks like:

POST /profiles
{
  "name": "Business name",
  "address": "The address",
  "phone": "0000000000" 
}

Now it is required that a Profile belongs to a Pricing Plan. So is it a good idea to do POST request like this with JSON?

POST /profiles
{
  "name": "Business name",
  "address": "The address",
  "phone": "0000000000"
  "plan": {
    "id": 1
  }
}

and then load the plan by the provided id and associate it with the profile being created:

@POST
@Path("/profiles")
public Response createProfile(Profile profile) {

    // load plan resource from DB
    Plan plan = em.find(Plan.class, profile.getPlan().getId())

    // associate
    profile.setPlan(plan);

    // persist profile
    em.perist(profile);
}

The Profile entity:

@Entity
public class Profile implements Serializable {

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

    @ManyToOne(fetch = FetchType.EAGER, optional = false)
    @JoinColumn(name = "plan_id", nullable = false)
    private Plan plan;

    private String name
    ...

    // getters and setters

}

The Plan entity:

@Entity
public class Plan implements Serializable {

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

    @NotNull
    @Column(nullable = false)
    private String name;

    @NotNull
    @Column(nullable = false, columnDefinition = "text")
    private String description;

    @NotNull
    @Column(nullable = false, precision = 8, scale = 2)
    private BigDecimal price;

    @NotNull
    @Column(nullable = false)
    private Integer days;

    @OneToMany(fetch = FetchType.LAZY, mappedBy="plan", cascade = CascadeType.ALL)
    private List<Profile> profiles;

    ...

}

In other words i am asking what I should pass to the request body in order to link a reference entity.

I would like to believe that something like this is more reasonable:

POST /plans/1/profiles

but according to the REST and JSON semantics what would be the best option?

I can also think of other ways such as providing the Plan id as a query param:

POST /profiles?planId=1

Answer 1

I would say you need to do the following:

Create profile with

POST: /profile

Assign plan with

PUT: /profile/<profile_id>
{
   "name": <optional>,
   "plan_id": <optional>,
   ...
}

First thing is you separate create and update (POST/PUT). Another is you state profile ID for update in URL.

You can set parameters you need to update in PUT request body and update only parameters which are set. Think it's fine with REST concept.