REST API Naming for public API for aggregate screen

Google Cloud Apigee
1

Hi,

We have come across situations where we have two screens where most of fields are same but in two situations.

E.g a) we search for junctions and it shows list of junctions with some commercial break availability time.

We have another situation b) where we show specific information for a junction and some additional fields e.g trailAvailability (but not commercial break).

We have an endpoint /junctions/searchResults (POST) that also accepts junction ids as well as search params (e.g date, time etc.).

So for option a) we use end point

POST - /junctions/search (with search params) and another one that gives trail info e.g /trailInfo.

and club (?) the result

POST - /junctions/search (with junction id) and get rest of information from /commercialbreak

and again club the result

I have a doubt shall I use two endpoints here that will aggregate results based on requirement

e.g GET /junctions with query params for search criteria (Use 1 above)

{

“junctions”:[{

“junctionid”":

“trailAvailability”:“”

}]

}

In this case it is junctions but it has some break information

and GET /junctions/{junctionid} (from 2 above)

{

“junctionid”":

“commercialBreakAvailability”:“”

}]

Or a single endpoint that can operate with flag isTrailReq and isCommercialBreak required.

With some response as below

Response-

{
  "junctions":[{
    "junctionid" : "", 
    "trailAvailability":"",
    "commercialBreakAvailability":""
  }]
}

In case if a user doesn’t need trail information than it may be -1 or 0. Removing a field may break contract.

To sum up I want to know the public facing API’s is it ok to expose per screen basis. Also, a naming convention such as /junction/{junctionId}/withTrailInfo is it OK as per rest principles.

thanks

2

I’m not able to follow the question.

But I can provide some comments.

First, I suggest thinking in APIs. You mentioned “Screens” several times. That won’t help you. Think in terms of APIs.

One way to do that: think of the specific requests that an API endpoint should handle, and the kinds of responses the endpoint should return. There should be no mention of screens.

Second, when asking for advice, try to explain in more general terms. I don’t know what junctions or commercial breaks are. Is there a 1:1 mapping between junction and commercial break? 1:N ? N:M ?

Third, URI design for resources calls for

/collectionname/{ID}

..where the “collectionname” is the type of resource, and is usually a plural noun. The {ID} is the identifier of the specific entity. If you design your URIs this way it makes it easier to reason about thing in a restful fashion.

Therefore

GET /products/1234

…will return the information associated to the product with identifier “1234”. This information is up to you, the designer of the API. It may include things like product category, size, availability, description, manufacturer, and so on.

Conversely,

GET /products

…might return a list of all products. More practically, it might return the FIRST PAGE of the list of all products, along with a cursor. The page length might be 10, 25, or 50… doesn’t matter. Subsequent calls to

GET /products?cursor=abcdefg

…will return subsequent pages of content.

If there are child entities, then you can chain those off the root entity, following the same collection name and identifier pattern. For example:

GET /products/1234/reviews

…might get the first page of consumer REVIEWS of the product in question, while

GET /products/1234/reviews/91883

…would return a specific review.

POST /products/1234/reviews

…would add a new review to the list, and

PUT /products/1234/reviews/91883

…would update the existing review with ID 91883.

The general principle is that NOUNS belong in the URL path, and VERBS get modeled by the HTTP method.

SEARCH is often a special case verb, and is sometimes given its own URL

POST /search?collection=products&query='query expression here'

To get multiple junctions based on ID, your query could be something like this:

/search?collection=junctions&query='id in [1234, 5678, 98181]'

If you want to be elaborate you could support boolean logic in the query language.

1 Like