5 ms·

I want to do it right, so I want to ask you: Question 1: Is there a de facto API/service description language standard out there? Optional question 2: Which w

I want to do it right, so I want to ask you: Question 1: Is there a de facto API/service description language standard out there? Optional question 2: Which would be the best choice for a decentralised internet of services?

gkoberger 11y ago
Answer 1: Swagger is the de facto. It seems to have low actual usage, but high midshare. As time goes on, I expect there to be a much higher usage of Swagger, since pretty much all API services accept it. (Other options include RAML, Blueprint and IO Docs, but Swagger has the momentum)
- 7373737373 11y ago
  Thanks! I figured the same. OpenAPI seems to be it. WSDL on the other hand seems to be dead and/or unusable. Even one of its creators described it as a "train wreck" :)
  - machinshin_ 11y ago
    Oh gods yah. WSDL should die painfully in a fire with all the people in its standards committee
    - junto 11y ago
      The basic WSDL stuff is OK. It's the WS-n extensions that are truly the Zed of this world.
  - mrweasel 11y ago
    >WSDL on the other hand seems to be dead Yeah, it's not. It's still what people in big enterprises do, or what people who want to do a quick API use. If you're a .NET developer it's pretty easy to consume WDSL/SOAP services, so you might be more inclined to just use it when creating your own webservices. There's of cause also the group that doesn't really know what they're doing, who just slaps a webservice method decorator on whatever internal function they wish to expose. Those are usually the worst APIs. But yes, WDSL is a train wreck.
- other_herbert 11y ago
  The c# version is swashbuckle... And I agree swagger is awesome... As long as the monkeys that consume your service will actually look at it
  - junto 11y ago
    We use Swagger on our .Net APIs. I need to have a look at Swashbuckle.
    - wing328hk 11y ago
      You may want to take a look at Swagger-Codegen (https://github.com/swagger-api/swagger-codegen https://github.com/swagger-api/swagger-codegen) as well to generate ASP.NET 5 server stub or C# API client given a Swagger/OpenAPI spec. Disclosure: I'm a top contributor to swagger-codegen
- machinshin_ 11y ago
  Another cool thing (potentially) about swagger is that AWS is supporting it for their API Gateway. You scan write a spec in swagger, tie it to AWS Lambda "functions", and AWS will create/update that . Still a WIP though :(
  - mooreds 11y ago
    Is this the project you are referencing? https://github.com/awslabs/aws-apigateway-importer https://github.com/awslabs/aws-apigateway-importer
- wing328hk 11y ago
  If you've a Swagger/OpenAPI spec, you can use Swagger Codegen (https://github.com/swagger-api/swagger-codegen https://github.com/swagger-api/swagger-codegen) to generate API clients (SDKs) in C#, Ruby, PHP, Java, ObjC, etc. Here is an example: https://github.com/wing328/petstore-php https://github.com/wing328/petstore-php A good starting point is to generate the SDK online: https://github.com/swagger-api/swagger-codegen#online-generators https://github.com/swagger-api/swagger-codegen#online-genera... Swagger-Codegen can also generate server stub in SpringMVC, PHP Slim and more. Disclosure: I'm a top contributor to the project.
  - 7373737373 11y ago
    Do you know any projects that reverse this functionality (generating API documentation from code)? I know that https://github.com/timothycrosley/hug https://github.com/timothycrosley/hug intends to provide this in the future, but could not find one for other languages (Javascript would be useful right now).
lmm 11y ago
WSDL is probably the best option, honestly. People will laugh but there are good implementations for all major languages. Personally I use thrift. I think that's the most fit-for-purpose way of doing it. But many people object to any standard that's not purely HTTP-based.

gkoberger 11y ago

Answer 1: Swagger is the de facto. It seems to have low actual usage, but high midshare. As time goes on, I expect there to be a much higher usage of Swagger, since pretty much all API services accept it. (Other options include RAML, Blueprint and IO Docs, but Swagger has the momentum)

7373737373 11y ago
Thanks! I figured the same. OpenAPI seems to be it. WSDL on the other hand seems to be dead and/or unusable. Even one of its creators described it as a "train wreck" :)
- machinshin_ 11y ago
  Oh gods yah. WSDL should die painfully in a fire with all the people in its standards committee
  - junto 11y ago
    The basic WSDL stuff is OK. It's the WS-n extensions that are truly the Zed of this world.
- mrweasel 11y ago
  >WSDL on the other hand seems to be dead Yeah, it's not. It's still what people in big enterprises do, or what people who want to do a quick API use. If you're a .NET developer it's pretty easy to consume WDSL/SOAP services, so you might be more inclined to just use it when creating your own webservices. There's of cause also the group that doesn't really know what they're doing, who just slaps a webservice method decorator on whatever internal function they wish to expose. Those are usually the worst APIs. But yes, WDSL is a train wreck.
other_herbert 11y ago
The c# version is swashbuckle... And I agree swagger is awesome... As long as the monkeys that consume your service will actually look at it
- junto 11y ago
  We use Swagger on our .Net APIs. I need to have a look at Swashbuckle.
  - wing328hk 11y ago
    You may want to take a look at Swagger-Codegen (https://github.com/swagger-api/swagger-codegen https://github.com/swagger-api/swagger-codegen) as well to generate ASP.NET 5 server stub or C# API client given a Swagger/OpenAPI spec. Disclosure: I'm a top contributor to swagger-codegen
machinshin_ 11y ago
Another cool thing (potentially) about swagger is that AWS is supporting it for their API Gateway. You scan write a spec in swagger, tie it to AWS Lambda "functions", and AWS will create/update that . Still a WIP though :(
- mooreds 11y ago
  Is this the project you are referencing? https://github.com/awslabs/aws-apigateway-importer https://github.com/awslabs/aws-apigateway-importer
wing328hk 11y ago
If you've a Swagger/OpenAPI spec, you can use Swagger Codegen (https://github.com/swagger-api/swagger-codegen https://github.com/swagger-api/swagger-codegen) to generate API clients (SDKs) in C#, Ruby, PHP, Java, ObjC, etc. Here is an example: https://github.com/wing328/petstore-php https://github.com/wing328/petstore-php A good starting point is to generate the SDK online: https://github.com/swagger-api/swagger-codegen#online-generators https://github.com/swagger-api/swagger-codegen#online-genera... Swagger-Codegen can also generate server stub in SpringMVC, PHP Slim and more. Disclosure: I'm a top contributor to the project.
- 7373737373 11y ago
  Do you know any projects that reverse this functionality (generating API documentation from code)? I know that https://github.com/timothycrosley/hug https://github.com/timothycrosley/hug intends to provide this in the future, but could not find one for other languages (Javascript would be useful right now).

lmm 11y ago

WSDL is probably the best option, honestly. People will laugh but there are good implementations for all major languages. Personally I use thrift. I think that's the most fit-for-purpose way of doing it. But many people object to any standard that's not purely HTTP-based.