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.
Related
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.
I am using Breeze JS and would like to implement a server with full CRUD functionality using Progress Openedge. The Breeze website talks a lot about being able to write your own server implementation but I can find no information describing the format of a save bundle that Breeze sends to the server. Does anyone know of any documentation or schema?
The documentation for this is buried in the DataServiceAdapters page. Look about halfway down, under the heading saveChanges (saveContext, saveBundle) -> promise.
There's an example of what the JSON looks like in this SO answer.
The SaveBundle is not documented for a very good reason: it has no definition in BreezeJS!
It could be any serialized object that your server requires to satisfy yoursaveChanges work flow. You can see that this is true by examining the a60_abstractDataServiceAdapter.js source in github:
proto._prepareSaveBundle = function (/*saveContext, saveBundle*/) {
...
throw new Error("Need a concrete implementation of _prepareSaveBundle");
};
Breeze does ship with an implementation b00_breeze.dataService.webApi that satisfies the expectations of the companion Breeze ASP.NET Web API helper classes such as ContextProvider. This implementation is worth studying if you decide to write your own server support code.
But it is only one of many possible implementations. An OData web server, for example, requires an entirely different package and format for "$batch" change-set saves. Only you know what's right for your "Progress Openedge" server.
All that said, we do delve into some critical aspects of the SaveBundle destined for Breeze Web API services in the documentation for "ContextProvider".
Feel free to follow-up with more specific questions after you've read that.
I'm looking for examples on how to implement a custom data provider for OData 4 and WebAPI (preferably for an in-memory untyped dataset).
Doese anyone know of any examples out there? My googeling turned up little of use.
I know of this example: http://msdn.microsoft.com/en-us/data/gg191846
But can't find the project-files for the example-code ... also it's from 2011 and things have changed since then...
You can refer to Web API OData Sample code at
https://aspnet.codeplex.com/SourceControl/latest
You can find the code at "Samples/WebApi/OData/v4/ODataUntypedSample" in the left panel.
There is another blog talking about "Typeless Entity Object Support in WebApi".
http://blogs.msdn.com/b/leohu/archive/2013/11/05/typeless-entity-object-support-in-webapi.aspx
Im new to breeze js, I understand that breeze has it's own query language related to OData
But I am trying to get breeze js working with a custom query language, as an example FIQL is
one of the form to make queries to backend, can we get breeze run with this type of query language.
Overview of FIQL :-
http://jaxenter.com/tutorial-smarter-search-with-fiql-and-apache-cxf-46876.html
(this is not a technical answer, at the very most it's an advice)
As mentionned from their website documentation :
Today, out of the box, the Breeze product ships with adapters for the
ASP.NET Web API and for OData. It also ships with .NET components that
interface with the Entity Framework and that generate Breeze metadata
from an Entity Framework model; that EF model could be developed code
first or database first. The Breeze client is in no way limited to
these technologies; they are merely the first backend components
available; we’d be thrilled to help you adapt Breeze to your preferred
server stack.
First question is whether
1) you want breeze to actually create FICL queries on the client and send them to a FICL service. This involves translating a client side breeze EntityQuery into FICL url syntax. If so you would need to create a new a 'uriBuilder' adapter.
2) you want to translate a breeze query already sent to your service into FIQL syntax on the server so that you can further refine the query and then send it on to your FICL service. If so you would need to create a breeze DataService endpoint.
Both of these are certainly possible.
If you are looking at the 1st option, take a look at the 'b000_uriBuilder.xxx' files in the breeze GitHub repo under the 'src' directory. There should be two 'uriBuilder.xxx' files, one which translates an EntityQuery into OData syntax and another that translates the EntityQuery into a new 'json' query syntax. There is also additional information on this 2nd syntax here:
http://www.getbreezenow.com/documentation/query-using-json
Both of these 'uriBuilder's make use an internal 'visitor' framework that we have not yet documented but should be reasonably understandable by looking at the source.
If you are looking at the 2nd option, I would recommend looking at the link mentioned above and then taking a look at the 'breeze.node.js' repo and the 'breeze-sequelize' subdir within it. In this repo we take a serialized server side breeze EntityQuery and translate it into a 'Node' Sequelize query that we can apply to a variety of backends.
Another option is to contact our professional services arm, at breeze#ideablade.com and ask them to assist in building the adapters for you or to ask for more detailed technical help.
I've read through the Breeze site, and found how one can populate Breeze's MetadataStore with OData metadata. I've also read the OData metadata capabilities (basically the CSDL definition) and skimmed through Breeze's metadata capabilities.
Two related questions on the subject:
How complete does Breeze cover the OData/CSDL metadata capabilities? I assume relationships entities and datatypes are all supported, but are there notable gaps to be aware of?
Can I export a Breeze MetadataStore (back) to CSDL? If not, is this on the roadmap of being supported? and if not :) how much of a coding effort would it be to add that support myself?
I guess this also relates to question #1 and to how close are the Breeze and OData metadata models to one another.
Thanks!
The Breeze "native" metadata format is a superset of what is available in the OData /CSDL. The idea was that we wanted to be able to support non-relational models and custom metadata in addition to what OData/CSDL does. In addition, we wanted something that was a bit more readable and used JSON as its native format and was easily extensible. I don't know of any gaps, but if you find any please let us know.
Exporting the metadata store as CSDL is not currently supported because it would be a lossy conversion. It certainly would be possible but for what purpose?.
Hope this helps.