I have used OData in my career quite a bit and now few of my colleagues from different teams recommended we move to JsonAPI and GraphQL as its not tied to Microsoft. I don't have much experience in both these query languages. As far as i know OData is a standard used by Salesforce, IBM, Microsoft and it is very mature. Why should one switch to JsonAPI and/or GraphQL? Is there a real benefit? Is JsonAPI and GraphQL new standard? Changing public api implementations based on popularity seems useless especially when there is no big benefit.
Can someone please enlighten me?
OData is a similar specification to JSON API. Both of them describe a standard protocol for creation and consumption of RESTful APIs. GraphQL is a totally different approach to API design and specifies a different way of querying API resources.
OData: Designed and developed at Microsoft since 2007, standardized by the OASIS consortium. The latest version V4 is submitted to ISO/IEC JTC 1 for approval as an international standard. Companies on the technical committee (TC) include CA Technologies, Citrix, IBM, Microsoft, Progress, Red Hat, SAP and SDL.
There are a number of libraries for popular programming languages - .NET, Java, JavaScript, PHP and Ruby. The spec allows dynamic resources and there's a service document which lists all API endpoints for clients to discover. Additionally, there's a metadata document describing the schema.
JSON API: JSON API was originally drafted by Yehuda Katz in May 2013. This first draft was extracted from the JSON transport implicitly defined by Ember Data’s REST adapter. The current stable version of the spec is 1.0. The JSON API spec is implemented for the majority of programming languages, for both the client and server sides.
JSON API supports HATEOAS through the link property in the JSON document. Other features include pagination, sorting, filtering and relationships. The JSON documents produced by JSON API servers are very verbose with lots of nested properties.
GraphQL: Developed at Facebook since 2015. The specification is still a working draft. It's quite popular among React fans and is mainly used in combination with React or Vue.js. Similar to GraphQL is Falcor, which is also relatively new.
While GraphQL makes use of HTTP, it is not considered REST, rather, an alternative to REST. Instead it makes use of a query/response model into a single (virtual) JSON document. This new model is somewhat nicer for developers to work with, but its benefits over REST are debatable. Given its young age, the ecosystem has yet to mature.
For the sake of clarity and completeness, I’ll include OpenAPI to the list, although it is not exactly an API specification. That can be confusing to some people. The OpenAPI standard is a language-agnostic standard for describing and defining APIs. Your API can follow one of the above standards (excluding GraphQL) and also be documented using OpenAPI 3, for example.
OpenAPI (a.k.a. Swagger): Developed as part of the OpenAPI Initiative and the Linux Foundation. Supported by big tech companies like Google, Microsoft, IBM, SAP, Oracle, Ebay and PayPal. The current version of the spec is 3.1.0. There are implementations for the majority of programming languages, as well as lots of additional tools like web UI generators, etc.
The best thing you get with specs like OpenAPI is the tooling around them - generators for API documentation pages, generators for client SDK code, etc.
This standard is probably the most commonly used today for API declaration, documentation and code generation. It is also supported by cloud providers like Amazon Web Services in their API Gateway.
In summary, OData and JSON API are both JSON data formats which add context and features (e.g. links) around your data, GraphQL is a totally different new way to query and mutate JSON data, and OpenAPI is the standard way to declare and document any RESTful API.
My personal opinion:
As you can see, there are quite a few RESTful specs out there, rather than a single universal standard. I agree with xumix here - they all seem to suffer from the "Not Invented Here" syndrome. The benefits of choosing any of the above are small, especially if your project is small or medium sized.
Does it matter which specification your API implements? Probably not much. Just focus on building a consistent and well-documented API.
Related
How can Breeze JS be used to consume a pure, simple, plain old RESTful API? Consider a web api endpoint that does not support OData and does not have Microsoft Entity Framework as the OR/M layer.
I see there's this Edmund's sample here, but I would like it to be more specific on how to manually setup BreezeJS metadata, since from what I understand about not having OData support is the fact that you lose out-of-the-box metadata resolution for the model consumed from an api endpoint. I quote from this Edmund example:
we have not yet described the Metadata Definition API properly. We ask that you rely on your intuition as you read this code ... your intuition will usually be correct. Please post questions to StackOveflow tagged with "breeze".
Is there any source of information on this topic that leaves intuition aside?
That Edmunds sample is so old, it pre-dates any of the documentation on how to write metadata.
Take a look at the Metadata by Hand topic in the BreezeJS documentation.
For a current project, I am trying to get a feel for how to effectively utilize Knockout 2.1.0, Upshot 1.0.0.2, ASP.NET MVC4, and Entity Framework 4.3. There are a lot of basic architectural questions which don't seem to have ready answers. I am enumerating several of my questions (in separate posts) in the hopes that someone can provide reasonable guidance for myself and others as we attempt to implement this combination in real-world applications.
In Steve Sanderson's awesome presentation on Knockout and Upshot.js at TechDays Netherlands in February, he mentioned Upshot can accommodate multiple methods of connecting to a server. (If you have not seen the presentation, it is well worth a watch. You can view it at http://channel9.msdn.com/Events/TechDays/Techdays-2012-the-Netherlands/2159.)
Unfortunately, he did not have time to detail what those communications mechanisms are or which was recommended and in what circumstances.
According to Denver Developer in his blog post titled “Digging into
Upshot.js” (http://denverdeveloper.wordpress.com/2012/03/07/digging-into-upshot-js/), there are three data providers exposed by Upshot.js.
These are:
• the default is DataProvider() and uses the /Submit method and the operation you provide it to get data using jQuery’s $.ajax method. (AG Note: I believe this generally connects with DbDataController objects exposed by WebAPI but am unsure of precisely what the limitations are.)
• the next is riaDataProvider() – similar to the first, but it uses the /json/SubmitChanges method and /json/{your opertion} to get data
• finally we also have odataDataProvider() – this one is quite different because it does not currently support updating data – it is read-only.
A number of closely related questions naturally present themselves regarding the selection of a provider for typical use.
Which data provider is better—the default data provider or the RIA data provider?
Which one is recommended for normal use and under what circumstances?
What are the performance implications of using the normal DataProvider vs the riaDataProvider?
On a related note, there appears to be very little documentation on upshot on the Internet. Other than drudging through the 4700+ lines of code in upshot.js, are there any other decent sources of documentation for this library?
The resources I have looked at so far include the following (plus a few more).
Source code from Steve Sanderson's SPA demo (available from http://blog.stevensanderson.com/2012/03/06/single-page-application-packages-and-samples/).
Source code from Bart Jolling's variations on Steve Sanderson's SPA demo application from his article on "Building Single Page Applications with ASP.NET MVC4" (parts 1-4). http://bartjolling.blogspot.com/2012/04/building-single-page-apps-with-aspnet.html
Big Shelf SPA demo code from ASP.NET site - http://www.asp.net/single-page-application/spa-samples/sample-bigshelf-application
Microsoft ASP.NET "A Tour through SPA" (basically focuses on upshot samples)
http://www.asp.net/single-page-application/spa-samples.
You should avoid using upshot and use http://www.breezejs.com/ instead
ASP.Net MVC Roadmap (note that upshot is not being developed further):
http://aspnetwebstack.codeplex.com/wikipage?title=Roadmap
keep an eye on the road map plus john Papa's blog (http://www.johnpapa.net/building-single-page-apps-with-knockout-jquery-and-web-api-ndash-the-story-begins) - that should keep
you on the right path
update : i just started playing around with hot towel - it roles Breeze, Durandal.js Knockout.js and Twitter Bootstrap (among others)
into a very nice template ...its looking pretty cool so far
https://github.com/johnpapa/HotTowel
Which provider to use depends on your server-side dataService type. In my practice they are:
WCF RIA service + upshot (with riaDataProvider) + knockout.
ASP.NET WEB API + upshot (with dataProvider) + knockout. (both will do good job for you!)
WCF data Service + upshot (with oDataProvider) + knockout. (read data only now) For oData server side service, "JayData" is a good option
I have a running java application which has some APIs, but none of them follow the REST standards. You need to use separate APIs(some are XML/JSON based and others are SMTP based) to achieve CRUS operations.
I really love the MVC architecture and the strict RESTfullness of ROR, so I am thinking to write a API only ROR service using rails-api gem. Is it recommended to write wrappers like this over the existing APIs to provide better REST APIs?
Note: The existing APIs are very old and I don't want to rewrite them from scratch.
Whether or not it's "recommended" depends on your needs, your timeframe, the ROI, etc. There's nothing wrong with writing a RESTful layer over existing APIs, if that's what you're really asking.
I prefer a "regular" API over one that has multiple access methods, irregular access patterns, etc. If I have the time and resources, putting a layer of abstraction over complexity is almost always valuable.
I am at a new company and one of our goals is to implement a document search portal for our team and our clients. I am a bit worried that if we use an external service provider like Salesforce or some other ECM in the cloud there will be a lot of integration work in the future. From a client perspective, these documents will also exist in the same bucket as our structured content (stored in the DB, not a MS Word doc).
If you have implemented document searching, what languages, frameworks, and technologies have you used? Do you have any failure stories? I don't have a problem using something out of the box, but I think it is important that we have control over the documents and the API to access them. I would like to use Rails if we go fully custom.
Depending on your licensing needs Lucene (LGPL) and Xapian (GPL) both are great, mature, fast search engine API's with bindings for a lot of languages. I've used both of them with great success.
Lucene is probably the safest choice because it is widely used and quite good.
The easiest way to benefit from Lucene is probably with Alfresco, which is a breeze to install, and has Lucene by default. It means you just need to install Alfresco, put your documents in the repository, and you can search for your documents using the powerful web search interface.
If you need to search programmatically, my recommendation is to use Alfresco' CMIS interface, which allows you to search in a REST way. The JCR API is also available.
I am new to both Django and Rails. I am thinking of developing an Web 2.0 style application and is planning to expose Restful services, which my UI tier would call to make CRUD operations (Something similar to ADO.NET Data services)
I am yet to decide on the platforms and is looking for some advice on which one to side develop on?
I am currently thinking of Ruby on Rails or Django.
The benefit of using DJango / Python is that I can move to google AppEngine in future with some code changes, but on the down side I hear DJango is not RESTful.
I am also new to both Ruby and Python. So, what would be your advice on which platform to use?
Well if you want to couple the view and controller with REST then you are right that django is not RESTful, because with django you would have to (de)serialize django objects and manipulate that by yourself in the front end using your favourite javascript framework. Saying that, if your only concern is to send and receive data RESTfully without caring how to do it, then django should be sufficient for you since you've already got your heart for it.
Django is fine for REST applications. Rails claims to provide some functionality to that makes REST easier, but it is largely inaccurate - things like human-readable URIs don't really matter to REST. Rails auto-generates POST/GET/DELETE/PUT stuff for you, but it's just as easy to do in Django too - and it really doesn't have much to do with REST, either, it's just proper HTTP usage.
REST is a general type of architecture, it has very clear constraints, but there is no one, single way to do a REST application. This is a good discussion by the architect of REST, Roy Fielding, on some common misconceptions: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
I recommend Python and Django, but not for REST-related reasons. (Better documentation, a saner API with Django, less nasty monkey patching and black magic, less coupling, etc)
A RESTful interface is used for building distributed applications. Does your UI tier and services tier really need to be physically separated? Seems overkill to me.