What is Reddit's opinion of swagger.io?

From 3.5 billion Reddit comments

Is the client facing API a rest service?

Assuming it is, use something like swagger (standard generation available for many languages) or MireDot (Java specific, very quick to get started).

Both of these take the exposed Java web service methods and create very nice looking documentation. Swagger requires extra documentation. Miredot reuses existing Javadoc tags.

I prefer having something like a routes file to see all the endpoints, but it makes the information fragmented. I have to go to one file to see what url params are passed and another for the logic. However, you can get the best of both worlds. Using something like swagger will give you a single place to look for a "big" picture perspective, while also keeping urls associated with their resource/controller/servlet. You even get an added bonus of documenting your apis (which is the main purpose of swagger).

Check out Swagger. It automatically generates a stubbed express server and a Postman-like web interface based on documentation you create. Really cool and saves you like 4 steps!

We have a large api code base that is heavily used. Some issues we ran into include:

• Versioning. Do you want to include /v1 /v2 etc in your urls?
• Documentation. Do you want to have an api spec in something like Swagger
• Testing, how are you testing your apis. Look at something like RunScope
• Monitoring and error reporting. Do you have tools in place to watch for errors? We use New Relic
• Do you want to support content negotiation (both xml an json) or just json?
• How are you doing authentication and authorization? Are you going to use Oauth. If so, will you set up your own token/provider server and handle claims?

No love for swagger?

It's different than Enunciate, you define your api in a standardized way, then it handles it from there...

EDIT: What is swagger?

2 There's http://jsonapi.org/

6 Agree. Consider service objects is when your controller method is becoming long (= probably doing too much business logic and not typical controller stuff such as rendering, redirecting, session, etc) and/or dealing with more than one model object. Don't overthink it, you can always extract it from fat controllers/models as you go along.

7 Try http://swagger.io/

I note that it's a Flask application. Is there a reason to not use some REST Flask extensions such as Flast-RESTful https://flask-restful.readthedocs.org/ ? This kind of extension can be plugged with Swagger -- http://swagger.io/ -- to easily discover the REST API.

Do you know if this framework exposes all scikit-learn features? Is there a Python (requests) client which can retrieve the result in a JSON format and turn it into a pandas DataFrame object as the scikit-learn models do?

You can try providing something like Swagger, WADL, or WSDL (yes, it can do REST). I prefer Swagger if I need to provide a machine readable definition.

You don't provide much information about the internal applications. If there is a prevailing client platform (Java) then it is common for you to provide a client library JAR.

Before you do anything else, read this ebook, it'll take like 20 minutes.: Web API Design by Apigee

It's, imho, one of the best practical REST API design handbooks around and guides you through a lot of the commonalities with advice on which you should do. Actually implementing everything covered can be a bit of a bear, but if you do, you'll have a hell of a service. IT's probably also overkill for an internal service.

Secondly, in terms of documentation, look at the Swagger framework for writing API specifications. Essentially, you describe the API as a YAML or JSON document, then they have tools which will turn that specification into 1) readable and interactive documentation, and 2) Client SDKs. There are also some tools which will generate stub methods for your server-side models from the spec for specific frameworks (SpringMVC, Strongloop Loopback, .Net WebAPI).

Designing a completely new and robust REST API is not trivial, so go slow, and read documentation from good APIs. Don't overengineer - if you're not building the next Amazon, you don't need AWS's level of complexity!

I'm a little confused as to what you're trying to do here. If there's no public API for a service then there's not much you can do except ask politely for them to implement it.

Are you talking about keeping a listing of APIs, like https://www.mashape.com/

Or are you talking about a standardised way to define APIs, like http://swagger.io/

Take a look at https://loopback.io which has been built on top of express.

What I like about it is that if you are doing simple CRUD then you just have to write a JSON files for defining your models. It will give the endpoints and http://swagger.io gui for all your models.

Not exactly the same but could be useful for anyone here currently developing their own REST APIs I would highly recommend the Swagger package for generating a UI over your API which reduces the need for tools like this http://swagger.io/

Would swagger/swagger-codegen be of any use here? It appears that the codegen tool has actively developed swift support.

We use GitLab flow at work, allow me to give you an example of how we use it. Let's say we're working on version 2.2.9 this sprint. Development fixes tickets in feature branches, do merge requests and get those branches in to master. Master gets merged in to the staging branch (multiple times per day) so it gets deployed automatically, so QA can test on the staging environment. Nearing the end of the sprint, dev and QA agree to sign off on the current staging code, so that gets merged to preproduction and if nothing goes wrong there, to production. So we promote revisions by merging them to the environment branches and automate from there. We use git tags to keep track of version numbers.

Dependency resolution between multiple apps is something we're still getting right. We already have extensive unit test coverage and recently we've made each app totally testable within isolation (e.g. backend apps are documented and testable with Swagger, frontend apps can have their backend calls stubbed) for dev and QA. Automated integration testing is up next. We're using go.cd for these fancy workflows because we had trouble getting Jenkins and it's plugins to play nice with each other.

At a meetup in Amsterdam I was at a presentation from a developer at bol.com (the Dutch Amazon) who talked about this problem as well. With 400 developers in teams on different schedules, building 100+ microservices, Octopus Deploy doesn't work because there's no time when everything is stable. They solved it by having each team being also responsible for supplying a correct API mock app for other teams to use in their development. That API is like a contract for their colleagues. When there's a breaking API change, they have to keep the old API around for at least 6 months while dependant teams make the transition.

Regarding the homepage, have you considered Swagger? Some people think that Swagger can completely replace API documentation for a sufficiently RESTful service. While I disagree with that, I would probably agree for many services with simple data models and mostly GET endpoints, like yours. There are probably some python/flask libraries for Swagger that hook directly into your endpoint and data model definitions, and produce the Swagger JSON automatically. Then you can use the Swagger UI to display that JSON in a very nice format.

Also, HATEOAS is overrated. That's right, bring it on, HATEoasRS.

swagger is kinda nice. the 2.0 spec is still in development though, but mostly useable. Apigee's a127 ties into swagger by using the swagger-editor. Those two are some options for you. I know the apigee folks did a little video about setting up an API really simply using their tools.

edit: urls:

• swagger
  
• a127

Since you're RESTful, you could use Swagger to define the APIs, then just generate all the client code (assuming there's a client/codegen for your particular stack). 100% consistent, and eliminates a bunch of book-keeping maintenance.

for stuff like this you'd probably want some API definition/documentation framework (like for example swagger). You define the API and then use swagger-codegen to generate client libs/server stubs. However I never actually tried it so I don't know how reliable it is.

I think some further clarification of your use case and stack would be helpful. What database, what stack, etc? In terms of the API usage, do you need security or just public read-only access?

Many modern web applications will have the front end consuming JSON from the backend via a REST API as a default so the "API" might simply be telling other developers what to call and perhaps creating some Swagger documentation, or informally telling them what to call.

At the company I work for, we write the API ourselves then annotate it using Swagger similar to this scala play example. We consume this Rest api code ourselves and swagger-ui provides a clean interface spec to it. I think this is similar to your description of generating the spec from the server implementation so there shouldn't be an issue, is that correct?

Can you explain more on generating a dynamic server from a spec file? I can't quite imagine how a non-code file (text?) file can generate advanced code functionality and didn't know swagger could do this.

Being that your sites aren't going to be getting a lot of traffic, why not keep the one you have now and run multiple instances? Multi-client systems are a PITA to build securely and you can run a heck of a lot of websites on a $10/month digitalocean droplet. You can still stick an API on each one. IIRC it's straightforward to build Django front-ends so even if you did host everybody's independently it wouldn't take that many resources.

For admin tools: WordPress uses the /admin/, Slack uses subdomains e.g. yoursite.slack.com/admin and Google uses admin.google.com/yoursite. It all depends on the architecture of your site. WordPress assumes a lot of single instances that can share a database, I imagine slack does sub-domains for security purposes and Google has the resources to build a single system.

You didn't ask for this, but I'll throw in my $0.02 for building an API:

• Make it easy to do GET requests from the URL because you'll be doing a lot of that while testing.
• Stick a version in front e.g. /api/v1/... that'll save you when you need to change things
• Use swagger to document your API and auto-generate your clients. They have generators for every language under the sun, that way it's easy to build more onto your service. Need an Android app, desktop app or data export tool? Done.

Great question! Swagger the specification was recently moved and renamed as the Open API Specification http://swagger.io/introducing-the-open-api-initiative.

The swagger brand is now just the commercial tools that Smartbear creates, not the actual specification. It's really confusing for the whole community, which is why we are generally including both OAS and Swagger 2 in all of our copy.

Yeah, RAML, API Blueprint, and Swagger all sort of do the same thing, they just each have their own opinionated way of doing things. I definitely recommend Swagger (the most popular option). I recently went to a conference that had the head of each product as guest speakers. I thought they would battle it out until one person becomes victorious. It turned out that they all felt the same way that competition was good and was pushing each other to add more features and really think through their design.

Usually you can use Swagger to document your API and get a webpage from which you can send requests and visualize their responses, or Postman.

Since you mentioned this is an exercise, it's really simple to create an HTML page with one or more buttons, which send AJAX requests to your API (you can use jQuery's .get(), .getJSON() or any other AJAX-enabled library) and output the response somewhere (a <pre> tag, a nicely-styled <div> or whatever).

I have heard good things about Swagger from API leaders in the community as well as the technical writers using it to work on the API documentation. Went to a API meetup with this as the topic and liked what I saw. http://swagger.io/

So this is basically just using swagger ?

How is the dynamic/real time update of the api documentation implemented?

Or do you mean NPR developers are supposed to update the specifications that generate the API documentation when they make changes to the code?

Swagger. Worked nicely for me, I really like the possibility to actually try out the API through the UI.

http://swagger.io

What comes to making sure that I have documented everything, I have tests to make sure that output of the swagger-doc is not broken and contains all the stuff suppose I have in the documentation. The output is JSON, so it is pretty much like testing the against the actual API.