consensus around REST API terminology

[Tom Johnson]

Is there a standard anywhere for official REST API terms?

It seems like the OpenAPI specification helps further consensus around terms. And yet, there are some terms that are still ambiguous, despite the specification.

With the Swagger Petstore, what would you call the following:

- /pet

- /pet/findByStatus

- /pet/findByTags

- /pet/{petId}

It seems the Swagger UI calls them "operations." Other terms I've seen include APIs, methods, objects, resources, or no name at all.

The terms I like are resources, methods, and endpoints. You have a pet "resource." This resource has a variety of "endpoints" available. Each endpoint uses a specific "method."

For each endpoint, there a specific "parameters" you can pass. The types of parameters include "body parameters," "header parameters," and "query string parameters." 

The endpoints usually have a sample "request" and a sample "response."

Do these terms represent the norm? I wish the OpenAPI spec didn't use "paths" and "operations," since these terms seem less common.

[Ron Ratovsky]

Hi Tom,

To me, endpoints is a bit more ambiguous and can mean a resource or an operation.

Swagger-ui does not refer to what you posted here operations. Swagger-ui refers to the combination of the http verb and the path as operations.

The petstore itself is not a good example of a REST API and is meant to be used to show the capabilities of Swagger rather than API design.

Looking at /pet and /pet/{petId}, to me they both represent a single resource.

I don’t think there’s a clear consensus of terminologies, and the OpenAPI is not really meant to resolve that (imho).

To me - /pet, /pet/{petId} and so on are paths.

Each path can have one or more operations (which include the HTTP Verb).

A resource is one or more paths, normally having a common root.

Endpoint will probably a more technical entity in the development aspect, and less in documentation.

Methods and operations are interchangeable.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.