This is my understanding:
Swagger is a notation/rules to write documentation. But why is it called a framework (like Angular/MVC)?
Swashbuckle is a program (JavaScript?) that generates the documentation (based on Swagger rules).
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Is this information correct? If not can someone explain in simple terms what Swagger, Swashbuckle, and Swashbuckle UI mean?
Also, what do I lose as an API developer if I do not use this?
Swagger is a notation/rules to write documentation. But why is it called a framework(Like angular/MVC)?
It is probably called a "framework" because its' purpose is to offer a systematic way of notating the interface of any RESTful service under the OpenAPI Specification. This is a big deal to developers because the spec is overseen by the Open API Initiative under the reputable Linux Foundation.
Swashbuckle is a program(javascript ?) that generates the documentation(based on Swagger rules)
Swashbuckle is more of a package (or a library) that you can make use of in your .NET Web API projects. It's purpose, as you have correctly indicated, is to generate the Swagger spec for your project. Additionally, the Swagger UI is contained within Swashbuckle so if you are developing an API in .NET it's really a nice one-stop shop of a package. It is almost entirely written in C#, not JavaScript.
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Yes, it does display the Swagger spec in a nice, human-friendly manner. However, Swashbuckle is not a necessary component for this. They are, aside from what I just said previously, completely mutually-exclusive.
Also what do I lose as an API developer, if I do not use this.
This is now entering into the realm of opinion but I'll try to be objective about it. I use Swashbuckle to assist in the creation of clients for my application APIs. After getting past the implementation learning curve (which wasn't much), this package has saved me quite a bit of time of writing the clients myself. Writing a web client is a trivial thing for small applications but enterprise-level applications have a tendency to keep growing and/or changing in complexity so it is nice to have the creation/updating of these clients completely automated.
In short, if you decide not to use it you must either resort on an alternative method of API client generation or write/update the clients yourself. If you are only developing the back end this may be completely pointless to you but it would certainly help whoever is responsible for creating the client apps that will consume your API services.
I hope these answers have been helpful. Cheers!
Related
I'm responsible for a project that is producing the server backend for an iOS application.
I would like to formally define the service interface for the clients to call so both the IOS, Android and server teams can practice contract-first development.
In the dark past we would have used WSDL and generated RPC-style client and server interop boilerplate from that. However this isn't the norm for IOS projects. We've also looked at Apache Thrift, but there is no code generator for Swift and the Objective-C generator seems to produce code that relies on deprecated IOS APIs.
Which brings us to REST, which works well as a way to move object state around. It seems less good for the kind of conversation that says "Hey server, do X with these parameters and return me a result." We just end up creating server-side controllers for particular actions, and those "define" the service's calling convention by being sticklers for getting the right parameters. Contract-last.
Is there a standard way to do contract-first web service development for iOS clients, or am I just going to have to treat documentation as the spec?
tl;dr: No.
I'm not aware of a 'standard' way of doing things, but many
client/server apps today do use some incarnation of a RESTful
interface. JSON is the usual format.
There are some well documented 3rd party utilities that can handle
this for you client side (like [RESTKit][1] in the case of REST), or
you can roll your own implementation based on apple's provided
NSURLSession or a networking library like [AFNetworking][2]
If needed, iOS can also handle socket-based communication. (3rd party
libs exist for this as well.)
[1]: https://github.com/RestKit/RestKit [2]:
http://nshipster.com/afnetworking-2/
We are trying to determine the best approach for adding a complex API layer to a modified version of nopCommerce. To back up a step, we're building out a custom site for a fashion/apparel manufacturer that has a lot of front-end application requirements and also needs to integrate with their cross platform apps (iOS, Android, Windows) which we're building with Xamarin. We've tentatively decided to start with nopCommerce as the base of our application to which we will add an API layer.
What we are unsure about is what is the best approach for implementing this in nopCommerce (or other similar .NET package)? The options we are considering are MVC vs WebAPI vs ServiceStack. We've been going thru many of the tutorials on PluralSight.com to get up to speed on app dev and API creation best practices, but there seem to be so many options, we're not sure where to start. We seem to be somewhat lost in a sea of implementation options for the API and how each is to be evaluated based on choice of the JS packages/frameworks used on the front-end for the web site and the tools chosen to create the apps.
If it matters, our basic requirements are:
Expand core of basic e-commerce package with some custom ERP style functionality
API layer that can work effectively with both a web front end (possibly as a SPA) and all cross platform apps built using Xamarin
Insure OAuth authentication across all interface types so we can just use social media logins consistently everywhere and can authenticate the user in any environment
Given this...
My question boils down to which of the three API methods (MVC vs WebAPI vs ServiceStack) is best for this?
In my humble opinion you should go with service stack, it´s easier to implement and a lot more flexible than web api, you can add/remove plugins for different functionalities you get a lot of infrastructure code OOB such as mechanisms to handle cache, loggers and other not just related to infrastructure such as validators and IOC container, etc.
you'll get a single mechanism for authentication including custom auth, oauth, oauth2, etc which works for linked in, facebook and google +, in that situation you´ll find yourself reusing a lot of code in across all your apps.
One other thing that I like about SS is that practically is just you and your IOC, nothig else, everything is quite simple to understand and to implement (there could be more than one hidden option or configuration you may miss in the documentation but you get a lot of support from the community in google groups or stackoverflow)
its easier to test (Unit testing) you already have abstractions for httprequest and httpresponse and a lot of more, you won´t find yourself doing wrappers for all the legacy web impl that are shipped with mvc.
SS is better than mvc web api in terms of performance, it got one of the fastest json serializers out there for .net
I´m working on a SPA app for the time beign and I have no regrets about my desition to get into the SS framework.
just my 2 cents.
I would say Web API is best option for the Services Layer
- http://www.asp.net/vnext/overview/aspnet-web-api
There are many advantages
- Web API has been in release cycle as separate component with latest features
- Security
- Versioning
- Attribute based routing
- OData integration
I got the PayPal integration working well using plain old HTTP POST using C# & .NET 2/3.5. I also get all transaction details in the response.
So, if I want to use WSDL (SOAP), will there be any advantage? (you can assume I know how to use web services)
Also, are there any examples on a complete C# project using this method? I already looked at http://www.codeproject.com/Articles/42894/Introduction-to-PayPal-for-C-ASP-NET-developers
but that page tells very little about how to make a fully functional transaction using WSDL.
Any ideas?
Or "if it ain't broke, don't fix it"
thanks!
I really don't work from WSDL's very often because I'm primarily a PHP developer. I have worked with them in Adobe Flex, though, and I gotta say I liked what I saw.
Basically, I was able to hook the WSDL up in Flex (which you can do in other IDE's as well) and it automatically gave me access to all of the API calls in the system. I could see all of the possible requests (functions) available to the web service as well as how to build them without even referring to much documentation.
When building HTTP requests directly (NVP/XML/JSON/etc) you gotta refer to documentation quite a bit to see how to build the request, and there's typically more trial and error involved, too, until you get things working. The WSDL helps you get around that, although, in reality you'll probably still be referring quite a bit to documentation.
The WSDL/SOAP tools I've used with PHP don't work nearly as nice as Flex or Visual Studio from what I've seen, so I typically stick to custom class libraries that build my requests for me. when I'm working in other platforms that utilize WSDL's a little nicer, though, I definitely prefer it.
I'm developing an ASP.NET MVC 3 application. I need this application to make use of an API I also need to implement. The API should both be available from ASP.NET MVC controller actions and Ajax. Now it is quite easy to make an API using ASP.NET MVC, but is it possible to use this from other ASP.NET MVC website actions? I guess the WCF is quite easy to use as it is just a service reference.
Other users of the API could be Windows Phone and iPhone.
Update:
Many only sees the API as a place where you consume data, but what about the part where you want to execute commands or do stuff, like add customer or change foo?
You may want to check our new WCF web API that was announced at PDC. We recently released a big upgrade. WCF Web API is designed specifically for allowing you to expose APIs to a range of clients in a pure HTTP manner. It is lightweight, offers a nice configuration story (no configuration files) and also is much easier to test.
You can download the bits at wcf.codeplex.com. It includes various samples, and there is also a set of NuGet packs for getting you started. Search for webapi.all on NuGet.
The way I like to do this is with RESTful controller actions. You can return JSON and use your calls with JavaScript on your own site. Other websites would almost certainly understand JSON and so they'd be able to consume your API pretty easily. This is much easier to write and test than a heavy WCF layer.
Check out this question for some example REST frameworks for MVC:
ASP.NET MVC REST frameworks
One of the newer ways of accomplishing data feeds is using OData. Scott Hanselman has a great introduction to it in Creating an OData API for StackOverflow including XML and JSON in 30 minutes.
It allows you to even throw LINQ queries into your URLs to retrieve exactly the data you need.
Open Data Protocol (Official site)
Open Data Protocol (MSDN, Microsoft)
WCF JSON binding was really terrible last time I used it. WCF also comes with all sorts of crazy rules about streams and how you have to use [MessageBody] attributes for everything.
It was a real PITA to me.
I knew I've answered something like this before:
What is the best way to implement a RESTful architecture in .NET today?
What are the ways of accessing web services on a BlackBerry device?
I've learned about XML for webservices. We use SAX and DOM parsers in Blackberry. Are there any more ideas like this?
I also want to know what KSOAP is and how to use it on BlackBerry.
AFAIK, kSOAP is a library that lets you post soap requests to your web service. If the service accepts a simple POST request, the easiest way would be to use HttpConnection. Here's a good tutorial
I've also used kXML2 for XML parsing, and that has worked out well for me till now.
Additionally, including 3rd party libraries is a pain (kSOAP and kXML), so here's a guide that will hopefully save you some time.
You can try http://wsclient.neurospeech.com/wsclient/java-android-blackberry/ which supports soap code generation for blackberry with additional library that manages everything, it generates native typed soap client and calling them is very easy. Otherwise you will be spending lot of time in xml to your types and types to xml conversions and so on. Plus date and many things are little complex to handle.