search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.65k stars 2.14k forks source link

Use of the term Resource instead of Route or URL Template #445

Open lukepuplett opened 5 years ago

lukepuplett commented 5 years ago

Hello

I like API Blueprint a lot, its so much better than any other API spec language or format because its much more aligned with the REST style. However, its still not quite there, and today I realised what is largely wrong with it.

The term Resource is incorrectly used. Consider that a URL is a URI which uniquely identifies a resource. The whole URL is a resource, such that ://api.net/things?a=1 could be pointing to a summary page of stock prices and ://api.net/things?a=2 could be a photo of a goat.

Therefore the terminology below is misleading or possible just wrong. What this actually is defining is a route or URL template. In some senses, the resources don't exist yet. Resources are born out of the mapping of a URL to code that handles and emits data to the wire.

In my above example, [/things?{id}] would be defined as a single resource. I think this leads to incorrect training of people's mental models of REST and brings about limited designs.

Often I think about a great REST API as being like a great website, driven by links and forms and the processing rules of the HTML media-type, but you'd not design a website in API Blueprint. Why not? If you can answer that then you'll be on your way to improving API Blueprint to be able to design great APIs and maybe great websites.

Thanks, Luke

From docs...

Resource Within the questions resource group, we have a resource called "Question Collection". This resource allows you to view a list of questions. The heading specifies the URI used to access the resource inside of square brackets at the end of the heading.

Question Collection [/questions]

lukepuplett commented 5 years ago

By the way, this came to me as I was writing the description underneath a "Resource" declaration heading. I often struggle to write these descriptions, then in a moment of clarity I thought that this thing isn't a resource at all, its a gateway to a whole load of different resources that serve different purposes depending upon the parameters supplied and the HTTP method in use.

My Business [/my-business/dialog?{id,businessType,skip,take}]

Provides resources for ….