Rest API Design - Image tagging application

Question

I am working on a tagging application to explore REST and Dropwizard.

Images can be uploaded and associated with tags. CRUD operation on those resources. Here the 2 resources are - image and tag. I am following the collections pattern in designing the rest endpoints . The DB schema of the mini application are as follows -

create table images(
   id BIGINT NOT NULL AUTO_INCREMENT,
   url VARCHAR(100) NOT NULL,
   isActive BOOLEAN default true,
   description BLOB NOT NULL,
   creation_time TIMESTAMP default now(),
   updation_time TIMESTAMP default now(),
   PRIMARY KEY ( id )
);


create table tags(
    id BIGINT NOT NULL AUTO_INCREMENT,
    description BLOB NOT NULL,
    is_active BOOLEAN default true,
    creation_time TIMESTAMP default now(),
    updation_time TIMESTAMP default now(),
    PRIMARY KEY( id )
);

create table images_tags(
    id BIGINT NOT NULL AUTO_INCREMENT,
    image_id BIGINT NOT NULL,
    tag_id BIGINT NOT NULL,
    is_active BOOLEAN default true,
    association_time TIMESTAMP default now(),
    PRIMARY KEY( id ),
    CONSTRAINT images_tags_uc UNIQUE (image_id,tag_id,is_active),
    FOREIGN KEY (image_id) REFERENCES images(id),
    FOREIGN KEY (tag_id) REFERENCES tags(id)
)

The endpoints designed are as follows -

GET /images
GET /images/{id}
GET /tags
GET /tags/{id}

POST /images - creation of a new image- body will contain the tags associated at image upload/creation in the system.
POST /tags - creation of a new tag

PUT /tags/{id} - update a tag
PUT /images/{id} - update a image

DELETE /tags/{id}
DELETE /images/{id}

GET /search/tags?query="ab*"&startIndex=0&limit=20 - search tags starting with ab

Now the use-case where I am stuck about the endpoint design.

A uploaded image can change the tag association . lets say image I1 at creation time got associated with tags t1,t2. Later user wants to remove t2 tag and add tag - t3,t4 from available tags to the image. How should this action/use-case be supported by API following REST principles.

My design -

PUT /images/{id}/tags/associate
{
"addedTags" :[t3,t4],
"removeTags" : [t2]
}

*My question is that is the above endpoint a good way of REST api design. If not what should the endpoint look like ? *

score 0 · Answer 1 · answered Jun 02 '20 at 13:45

Forget about your REST API - think about how you would achieve the outcome you want with a collection of web pages, and forms that the operator can fill in and submit.

That will give you important insights into how your REST API should be designed.

The important element here is that a REST API doesn't expose your data model to the web, it exposes your affordance model to the web; we're defining families of resources (documents) that allow the consumer to use general purpose tools to interact with our business.

Now, if you aren't happy with web forms, a reasonable alternative is to define your API in terms of edits to the documents themselves. All of the interaction would look something like

GET /e61954b9-a6a5-4a19-a7aa-0d2ca436dc82

200 OK

{original contents}

Client makes edits to its local copy of the document, then...

PUT /e61954b9-a6a5-4a19-a7aa-0d2ca436dc82

{updated contents}

200 OK

So for the use case you describe, we might GET a copy of a document that describes the image and the list of tags associated with it, then modify our local copy to remove the unwanted tags and add new tags as necessary, the PUT a copy of our local representation back to the server.

Depending on how many different kinds of use cases we needed to support, there might be many resources available for interacting with a single image in your system.

Rest API Design - Image tagging application

1 Answers1