Hacker News Reader

Comment by 7373737373 | Hacker News Reader

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?

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)

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" :)

Oh gods yah. WSDL should die painfully in a fire with all the people in its standards committee

The basic WSDL stuff is OK. It's the WS-n extensions that are truly the Zed of this world.

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

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

We use Swagger on our .Net APIs. I need to have a look at Swashbuckle.

You may want to take a look at 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

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 :(

Is this the project you are referencing? https://github.com/awslabs/aws-apigateway-importer

If you've a Swagger/OpenAPI spec, you can use 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

A good starting point is to generate the SDK online: 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.

Do you know any projects that reverse this functionality (generating API documentation from code)? I know that 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).

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.

Reply on news.ycombinator.com