API design question - multiple endpoints?

297 views
Skip to first unread message

jim lee

unread,
May 5, 2017, 12:49:56 PM5/5/17
to API Craft
Stuck on API design principles (and lack there of) and hoped I could get a few wise opinions...

We are converting an old monolith to modern micro services and getting stuck on the design conventions that may bite us down the road.  My current conundrum:

Hypothetically... we have large widgets and small widgets.  Large widgets are extra complex and store lots of data across a bunch of tables.  Small widgets are straight forward and stored in one table.  We want to make a public API with a new fancy JS site that mostly presents these widgets separately but in some less common occurrences we will present them all together.

So, trying to decide which is the best design to present these to be able to separate or show all as needed. (and do not want to do just one widget resource where type="small" due to the discrepancy between # of fields, effort to get data, etc.)

In one API endpoint?
e.g. 
/api/widgets 

or is it advantageous to break into 3 endpoints?
e.g. 
/api/widgets
/api/largeWidgets
/api/smallWidgets

 Or does it even matter?

-----

One API GET resource example:
response:
{ "largeWidgets":[
   {
    "value 1": "Awesome widget",
    ...
    "value 25": "123456"
   },
   {
    "value 1": "Big ol' widget",
    ...
    "value 25": "123456"
   }
  ], "smallWidget":[
    "value 1": "tiny widget",
    "value 2": "1",
    "value 3": "123456"
]
}

Multiple endpoint GET response example

largeWidgets response example:

{
   {
    "value1": "Awesome widget",
    ...
    "value 25": "123456"
   },
   {
    "value1": "Big ol' widget",
    ...
    "value 25": "123456"
   }
}

smallWidgets response example:

{
    "value 1": "tiny widget",
    "value 2": "1",
    "value 3": "123456"
}

Widgets response example:

{
   {
    "type": "large",
    "value1": "Large widget",
    ...
    "value 25": "123456"
   },
   {
    "type": small",
    "value1": "Small widget",
    ...
    "value 25": ""
   }
}

Huge thanks for any insight, advice, experiences 

Johan Groenen

unread,
May 6, 2017, 12:05:01 PM5/6/17
to API Craft
Not clear from your example (what kind of information is returned, what is the domain meaning of a "widget"), but seems to me that the "values" (val1, ..., val25) should actually be named attributes (height, width, time, ...). In that case, you have two different classes, so to me would make more sense to have two endpoints:

/smallwidgets/

/largewidgets/

I think you also need to think about the class name (widget seems a bit generic).

Andrew B

unread,
May 6, 2017, 1:57:03 PM5/6/17
to API Craft
How about:

GET /widgets/{}/
GET /widgets/{}/smallDetail
GET /widgets/{}/largeDetail

Andrew B

unread,
May 6, 2017, 1:59:58 PM5/6/17
to API Craft
Oops sorry, you were asking about the set:

How about

GET /api/widgets?type=large

Johan Groenen

unread,
May 7, 2017, 10:51:52 AM5/7/17
to API Craft
https://sourcemaking.com/refactoring/replace-type-code-with-subclasses

Op zaterdag 6 mei 2017 19:59:58 UTC+2 schreef Andrew B:

jim lee

unread,
May 12, 2017, 12:09:21 PM5/12/17
to API Craft
Delayed response... This was super helpful , thank you.!
Reply all
Reply to author
Forward
0 new messages