Swagger for non-REST APIs

[Dave Merrill]

Hi folks, I'm brand new to Swagger, just looking at its capabilities.

Is it possible to use Swagger to document APIs that don't use REST, just standard component.someMethod(someArg="foo", [...]) calls?

Thanks.

[tony tam]

Hi Dave, you sort of can, but it’s going a bit against the grain.  The ecosystem is more intended for rest-like APIs, although being “strictly” or even “proper” restful is certainly not a requirement.

--
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.

[Dave Merrill]

Thanks for getting back Tony.

A bit more context: An app I work on has a largely HTML/JS/Ajax front end, but also supports server-side customization, where our back-end methods can be called by native customer code, no HTTP involved. Additionally, the parts that are called via HTTP/Ajax aren't REST at all, they're simple GET or POST requests to a common front controller URL, with the object and method to be called and any parameters in URL or form variables.

From what I've seen of Swagger and API Blueprint, both require a) different URI endpoints for different target objects, b) different HTTP verbs for the canonical REST/CRUD actions, and c) REST-specific HTTP response codes. Am I right about that? If so, as you say, it's kind of a square peg/round hole problem. The editing environment, mocks, generated stubs, really the whole ecosystem, would all fight you if you tried to use them in that context.

If that's the case, are you aware of any API design tools or description languages that might be a better fit?

Thanks again very much for your time and thoughts,
Dave

On Monday, April 17, 2017 at 1:36:46 PM UTC-4, tony tam wrote:

Hi Dave, you sort of can, but it’s going a bit against the grain.  The ecosystem is more intended for rest-like APIs, although being “strictly” or even “proper” restful is certainly not a requirement.

On Apr 17, 2017, at 5:00 AM, Dave Merrill wrote:

Hi folks, I'm brand new to Swagger, just looking at its capabilities.

Is it possible to use Swagger to document APIs that don't use REST, just standard component.someMethod(someArg="foo", [...]) calls?

Thanks.

--
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-swaggersocket+unsub...@googlegroups.com.

[tony tam]

Hi Dave, you are describing a fairly typical RPC-style API, and it’s difficult to model those call with any REST framework.

You can, however, look at what is being done in the 3.0 version of the specification behind Swagger (now called the Open API Specification) and see that we are supporting different schemas for the input.  You can always say that the “input is an object” and let the user (either client or server) figure it out.

If you can constrain the types of objects being passed to the system, you can start using polymorphism via discriminator in the current 2.0 specification.  Then you can say that you’re passing a “Fruit” and that fruit may be of type “Apple”, “Pair”, etc.  It sounds like that my be not usable for what you’re looking to do.  In the 3.0 spec, you can say that the input is “oneOf” a fixed set of types, which could be “Fruit, Automobile, Furniture, or plain Object” (for example) which does expand the options for inputs.  Again, it is intended to be a somewhat constrained set, which is what allows the tooling to be useful.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Dave Merrill]

Actually, all of our inputs and outputs are quite strong typed, not in the Java actually-is-an-instance-of sense, since some access is across the web, but they are all named types, most of which have some sort of validation (regex, enum, array-of-this-type-of-object, etc).

How do you guess the changes you're talking about will affect the API docs UI?

None of those enhancements are likely to do away with the REST verbs, HTTP return codes, etc, right?

Not to drag you off topic, but are you aware of any tools for designing, documenting, and testing APIs along the lines I'm talking about?

On Mon, Apr 17, 2017 at 2:09 PM, tony tam <feh...@gmail.com> wrote:

Hi Dave, you are describing a fairly typical RPC-style API, and it’s difficult to model those call with any REST framework.

You can, however, look at what is being done in the 3.0 version of the specification behind Swagger (now called the Open API Specification) and see that we are supporting different schemas for the input.  You can always say that the “input is an object” and let the user (either client or server) figure it out.

If you can constrain the types of objects being passed to the system, you can start using polymorphism via discriminator in the current 2.0 specification.  Then you can say that you’re passing a “Fruit” and that fruit may be of type “Apple”, “Pair”, etc.  It sounds like that my be not usable for what you’re looking to do.  In the 3.0 spec, you can say that the input is “oneOf” a fixed set of types, which could be “Fruit, Automobile, Furniture, or plain Object” (for example) which does expand the options for inputs.  Again, it is intended to be a somewhat constrained set, which is what allows the tooling to be useful.

On Apr 17, 2017, at 11:05 AM, Dave Merrill <enig...@gmail.com> wrote:

Thanks for getting back Tony.

A bit more context: An app I work on has a largely HTML/JS/Ajax front end, but also supports server-side customization, where our back-end methods can be called by native customer code, no HTTP involved. Additionally, the parts that are called via HTTP/Ajax aren't REST at all, they're simple GET or POST requests to a common front controller URL, with the object and method to be called and any parameters in URL or form variables.

From what I've seen of Swagger and API Blueprint, both require a) different URI endpoints for different target objects, b) different HTTP verbs for the canonical REST/CRUD actions, and c) REST-specific HTTP response codes. Am I right about that? If so, as you say, it's kind of a square peg/round hole problem. The editing environment, mocks, generated stubs, really the whole ecosystem, would all fight you if you tried to use them in that context.

If that's the case, are you aware of any API design tools or description languages that might be a better fit?

Thanks again very much for your time and thoughts,
Dave


On Monday, April 17, 2017 at 1:36:46 PM UTC-4, tony tam wrote:

Hi Dave, you sort of can, but it’s going a bit against the grain.  The ecosystem is more intended for rest-like APIs, although being “strictly” or even “proper” restful is certainly not a requirement.

On Apr 17, 2017, at 5:00 AM, Dave Merrill wrote:

Hi folks, I'm brand new to Swagger, just looking at its capabilities.

Is it possible to use Swagger to document APIs that don't use REST, just standard component.someMethod(someArg="foo", [...]) calls?

Thanks.

--
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-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/Sl1bMWSKqYU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[tony tam]

Hi Dave, with the changes coming in the 3.0 spec, you can define schemas for the input payloads and expect that inputs will have to match a schema to “get in”.  So that is a good thing and seems to satisfy your first question.

From the docs point of view, we are currently working on how that will look in the swagger-ui.  Most likely there will be an area where a payload can be described, and different schemas / models to see that your model matches against them.  And in this case, this doesn’t have much to do with the HTTP method, although we have updated the spec to make it clear that methods which do not define behavior (like GET) for request payloads may not have request payloads…

If you’re looking for pure RPC-style modeling tools, you might look at what is there for modeling gRPC since it’s fairly modern and popular.  That is for describing protobufs but the concept is the same.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Dave Merrill]

Thanks Tony, will investigate.

Dave

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/Sl1bMWSKqYU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.