OData?

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

Personally I am working on an OData service provider at work and it seems this API could have used a more open standard like OData which can return XML or JSON depending on the client headers. And it has much better support for queries.

http://www.odata.org/

Opinions?

OData?

in API Development

Posted by: Khisanth.2948

Khisanth.2948

You are doing the equivalent of posting a link to a video and having “Comments?” as the text.

Since you are bringing it up. What would be the advantage of adding XML support? OData in general? What problems with the current approach would it solve or help alleviate? Just ‘support XML’ doesn’t seem like a very compelling to do this. Support for queries can also be done without any this.

This looks like a lot of extra complexity and overhead for …. well I am not sure what. I guess that is for you to answer.

OData?

in API Development

Posted by: Killer Rhino.6794

Killer Rhino.6794

Yeah, I’m also confused. As with the previous commentator, what problem are you trying to solve?

Creator of GW2Kit

OData?

in API Development

Posted by: smiley.1438

smiley.1438

which can return XML or JSON depending on the client headers

https://developer.mozilla.org/de/docs/HTTP/Access_control_CORS says

A simple cross-site request is one that:

  • Only uses GET, HEAD or POST. If POST is used to send data to the server, the Content-Type of the data sent to the server with the HTTP POST request is one of application/x-www-form-urlencoded, multipart/form-data, or text/plain.
  • Does not set custom headers with the HTTP Request (such as X-Modified, etc.)

So what exactly would be the advantage over typing a different file extension and adding some query parameters? There’s not much information in the link you posted.

Yeah, I’m also confused. As with the previous commentator, what problem are you trying to solve?

this.

also these:

Don’t get me wrong, but personally i’d kill XML with fire

Not to speak of the overhead XML has compared to JSON.

(edited by smiley.1438)

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

Because then you can do queries, filters, etc. all through the URL.

http://www.odata.org/documentation/odata-version-3-0/url-conventions/

It also have full CRUD support for maybe something like a new trading post api:

GET: Gets one or many entries.
POST: Create a new entry.
PUT: Update an existing entry
DELETE: Remove an entry.

You can also see the metadata describing the objects returned by the database instead of just relying on external API documentations in the wiki.

http://services.odata.org/V4/(S(gasi45ui0rqgrijmvv4kzw14))/OData/OData.svc/$metadata

It is an open standard that is supported by numerous clients, even in Android, IOS and Windows Phone. Even Netflix has moved to expose its data through OData.

The biggest con I see would be the development cost of moving to OData, even though it already has libraries for .NET, Java, and Javascript.

OData?

in API Development

Posted by: Khisanth.2948

Khisanth.2948

Query parameters aren’t exactly exclusive to OData. Anything that is accessed through HTTP could support that. That is more a question of whether or not ANet wants to support(and have the resources for the development of that feature). Simply implementing querying and filtering would probably require a lot less development time than dealing with the whole OData stack. The same goes for CRUD.

Metadata is nice but still not as nice as good documentation. It is certainly not an acceptable replacement for documentation. It would probably be nice when the data model changes and you don’t have to change any code but I don’t see that happening much for GW2.

The only advantage I can see with OData is that if you happen to have an OData library already then you can pull the data with less work. If you don’t then you will either need to find one or face significant overheads(compared to HTTP requests + JSON decoding) for implementing one.

TL;DR
More work for questionable gains that could be acquired through alternative means.

OData?

in API Development

Posted by: Killer Rhino.6794

Killer Rhino.6794

It also have full CRUD support for maybe something like a new trading post api …

As it were, for now GW2’s APIs only have one mode: GET. I could see how OData might make a service you’re designing internally more robust, though.

You can also see the metadata describing the objects returned by the database

I can’t say this enough: No XML!

Look, a more descriptive data format might make sense for your use case, but in most other cases, it’s a waste of bytes that the majority of wrappers probably won’t make use of.

Here’s an example of why descriptive data-types are so limiting

map-names.json, world-names.json, and event-names.json all return the same object structure — ‘id’ and ‘name’. However, it would appear that map-names.json and world-names.json have IDs that are numeric, while event-names.json have IDs that are alphanumeric.

The truth is, it shouldn’t matter how these object properties get represented client-side. Individual developers would handle this particular idiosyncrasy in whatever implementation makes sense for their wrapper’s particular language. The wise developer might use the same wrapper object to map to all three. In the end, the only thing that really matters is that the GW2 API defines name objects in two parts: — ‘id’ and ‘name’, not “some int” and “some string”. And trying to impose such via the service’s responses would be a complete waste.

Creator of GW2Kit

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

I can’t say this enough: No XML!

OData supports JSON format as well:

http://www.odata.org/documentation/odata-version-3-0/json-verbose-format/

As for the metadata, I agree that not being able to list them in JSON format is a slight drawback. However, you can get the service document in JSON, which is a subset of the metadata. It doesn’t have the type information but you can see the entity sets (i.e. the available entry points to the service).

http://odata.informea.org/services/odata.svc?$format=json

The main advantage of supporting an open standard is promoting code reuse in both the client and server.

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: Killer Rhino.6794

Killer Rhino.6794

As for the metadata, I agree that not being able to list them in JSON format is a slight drawback.

You might have misinterpreted my point. Or I might be misunderstand you.

Either way, I don’t want metadata or type information in my responses. JSON is simple and easy to use because it eschews this sort of verbosity.

Creator of GW2Kit

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

Either way, I don’t want metadata or type information in my responses. JSON is simple and easy to use because it eschews this sort of verbosity.

As I have already said, it supports JSON as well. The client chooses the format that it wants to deal with.

You don’t need to query the metadata on every call. In fact, you don’t even need to query the metadata at all if you don’t want to, assuming that the service has not changed or has not changed in a way that may break legacy clients. But it is nice to have metadata for those who choose to build more adaptable clients or if your development platform supports intellisense from an OData Web service reference (e.g. Visual Studio).

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: Morhyn.8032

Morhyn.8032

I’d like more standardized responses from the API, for sure. But I don’t need some overly verbose Microsoft garbage as the resolution to that problem. Might as well opine that it should support WSDL while you’re at it (ugh).

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

I’d like more standardized responses from the API, for sure. But I don’t need some overly verbose Microsoft garbage as the resolution to that problem. Might as well opine that it should support WSDL while you’re at it (ugh).

Define what “overly verbose Microsoft garbage” is?

Like I have said, you don’t need to use XML. You can request for JSON responses as a client.

Besides WSDL is a W3C standard, not a Microsoft standard. At least the latest version of it is.

You can go with supporting an open standard like OData or you can go with a proprietary web service API like what we have now. I would vote to support open standards myself.

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: smiley.1438

smiley.1438

a proprietary web service API like what we have now.

Where exactly is a simple JSON response “proprietary”?

OData?

in API Development

Posted by: StevenL.3761

StevenL.3761

What DarkSpirit is getting at is that the response objects do not follow any standards, meaning that any client library that wants to use the API has to be custom-tailored.
On the other hand, there are many REST libraries out there that have OData support baked into it, meaning you can just plug the library in to your program and start using the API right away.

In my humble opinion, OData support would be a huge improvement, but a lot of its potential would go to waste because the APIs are read-only.

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

In my humble opinion, OData support would be a huge improvement, but a lot of its potential would go to waste because the APIs are read-only.

Even if all the APIs are read-only, OData also contributes to a much richer set of query syntax compared to what we have now. If you can call what we have now, a query syntax. For example, you would be able to ask the server to only return a list of all the light armors in a single request, not just one item per request based on only the item id. You have support for $select, $filter, $orderby, $top, $skip, $count, $search, functionality and much more. How is that not an improvement over what we have now?

Besides, if they do want to provide support for a Trading Post API, then you can have full CRUD support, not just reads.

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: StevenL.3761

StevenL.3761

That’s the main reason why I’d like to see OData support. Sorting through megabytes of response data just to get maybe 5 or 6 objects that match a set of parameters is just not very RESTful.

OData?

in API Development

Posted by: Killer Rhino.6794

Killer Rhino.6794

That’s the main reason why I’d like to see OData support. Sorting through megabytes of response data just to get maybe 5 or 6 objects that match a set of parameters is just not very RESTful.

So let’s solve that problem with a proprietary protocol nobody has every heard of!

/sarcasm

Creator of GW2Kit

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

a proprietary web service API like what we have now.

Where exactly is a simple JSON response “proprietary”?

JSON is an open data representation standard, you can use an open data representation standard like JSON and yet have a proprietary data access protocol to access your data.

OData, on the other hand, is an open data access protocol standard that supports BOTH JSON and XML data representation formats, it returns response data in JSON or XML depending on the choice made by the client’s HTTP “Accept” header.

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: Morhyn.8032

Morhyn.8032

I’d like more standardized responses from the API, for sure. But I don’t need some overly verbose Microsoft garbage as the resolution to that problem. Might as well opine that it should support WSDL while you’re at it (ugh).

Define what “overly verbose Microsoft garbage” is?

Like I have said, you don’t need to use XML. You can request for JSON responses as a client.

Besides WSDL is a W3C standard, not a Microsoft standard. At least the latest version of it is.

You can go with supporting an open standard like OData or you can go with a proprietary web service API like what we have now. I would vote to support open standards myself.

XML => overly verbose
ODATA => Created by Microsoft

Thus, “overly verbose Microsoft garbage.”

Also, I did not claim WSDL is a Microsoft standard. I said “since you’re asking for a format that cumbersome for anyone not using a Microsoft IDE, or one that follows their lead, you might as well go ahead and ask for an equally painful standard (WSDL).”

Seriously, there are only two things that need to be addressed in the next version of the API to make the current API better as-is (i.e. not including new features):

1. A standard response format. None of this objects keyed with the name of the endpoint in one method and not keyed that way in another (my preference).

2. Documentation that clearly outlines the responses you should expect from the endpoints with zero ambiguity (I’m looking at you item_details.json).

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

I’d like more standardized responses from the API, for sure. But I don’t need some overly verbose Microsoft garbage as the resolution to that problem. Might as well opine that it should support WSDL while you’re at it (ugh).

Define what “overly verbose Microsoft garbage” is?

Like I have said, you don’t need to use XML. You can request for JSON responses as a client.

Besides WSDL is a W3C standard, not a Microsoft standard. At least the latest version of it is.

You can go with supporting an open standard like OData or you can go with a proprietary web service API like what we have now. I would vote to support open standards myself.

XML => overly verbose
ODATA => Created by Microsoft

Thus, “overly verbose Microsoft garbage.”

Also, I did not claim WSDL is a Microsoft standard. I said “since you’re asking for a format that cumbersome for anyone not using a Microsoft IDE, or one that follows their lead, you might as well go ahead and ask for an equally painful standard (WSDL).”

Seriously, there are only two things that need to be addressed in the next version of the API to make the current API better as-is (i.e. not including new features):

1. A standard response format. None of this objects keyed with the name of the endpoint in one method and not keyed that way in another (my preference).

2. Documentation that clearly outlines the responses you should expect from the endpoints with zero ambiguity (I’m looking at you item_details.json).

It looks like you are biased against technologies from Microsoft simply because you hate Microsoft instead of being able to evaluate them based on their own merits. So there is no point for me to hold any technical discussion with you any further since you are judging based solely on original brands. Besides, if you keep complaining about XML being too verbose, then which part of the “it also supports JSON” mentioned here, here, or here do you not understand?

I am looking for comments from technical people, based on software engineering and computer science concepts on this thread not brand name-marketing rubbish.

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: Morhyn.8032

Morhyn.8032

~shrug~

When I do a search for OData, which I had never heard of before reading this thread, almost all of the top results are from Microsoft oriented sites/projects — https://duckduckgo.com/?q=odata

The first interesting result that pertains to this conversation is a StackOverflow question — http://stackoverflow.com/questions/2458407/difference-between-odata-and-rest-web-services . The accepted answer should tell you why no one here is excited by your suggestion:

As Franci said, OData is based on Atom Pub. However, they have layered some functionality on top and unfortunately have ignored some of the REST constraints in the process.

The querying capability of an OData service requires you to construct URIs based on information that is not available, or linked to in the response. It is what REST people call out-of-band information and introduces hidden coupling between the client and server.

While the current API isn’t exactly transparent, it doesn’t bind you to using a specific technology (other than being able to parse text). OData is brining nothing useful to the table.

I haven’t addressed your insistence on “it also supports JSON” because there really isn’t any point. Why would it supporting JSON immediately make it a worthwhile change? JSON as an output format doesn’t make the added complexity of being able to get the output worth it.

I’m not “biased against technologies from Microsoft simply because [I] hate Microsoft.” But I’m certainly no fan of their style and won’t just accept using their solution when a simpler, more open one, is possible.

OData?

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

~shrug~

When I do a search for OData, which I had never heard of before reading this thread, almost all of the top results are from Microsoft oriented sites/projects — https://duckduckgo.com/?q=odata

The first interesting result that pertains to this conversation is a StackOverflow question — http://stackoverflow.com/questions/2458407/difference-between-odata-and-rest-web-services . The accepted answer should tell you why no one here is excited by your suggestion:

As Franci said, OData is based on Atom Pub. However, they have layered some functionality on top and unfortunately have ignored some of the REST constraints in the process.

The querying capability of an OData service requires you to construct URIs based on information that is not available, or linked to in the response. It is what REST people call out-of-band information and introduces hidden coupling between the client and server.

Do you not realize that the drawbacks mentioned in that link also exists in ArenaNet’s current implementation of their API? The link addresses issues from some developer on how OData can be improved upon for generic purposes. Do we need to “create media types to describe these key pieces of data” as mentioned in the link for ArenaNet’s API? Not really. Do we currently “construct URIs based on information that is not available or linked to in the response” for the current ArenaNet’s API? Of course we do.

Therefore, if supporting “these features” are really that important to you, rather than going ahead with the current implementation, which is also lacking, you should be proposing another open REST protocol standard that support “these features”, if you can.

OData is brining nothing useful to the table.

Since I hate repeating myself: https://forum-en.gw2archive.eu/forum/community/api/OData/first#post3704642

I haven’t addressed your insistence on “it also supports JSON” because there really isn’t any point. Why would it supporting JSON immediately make it a worthwhile change? JSON as an output format doesn’t make the added complexity of being able to get the output worth it.

That is to address your complaints against XML being “overly verbose”.

I’m not “biased against technologies from Microsoft simply because [I] hate Microsoft.” But I’m certainly no fan of their style and won’t just accept using their solution when a simpler, more open one, is possible.

Again that sounds like more brand name prejudice than anything else. What is “their style”? Their style of supporting XML? Many companies use XML too. Their style of ever proposing WSDL in their ancient history? WSDL is a supported standard of W3C.

If I take a section of code written by Microsoft and a section of code written by Google are you able to tell the difference, other than the copyright statement on top? I ask because I have worked in the Software industry for 20+ years and personally know friends, whom I have worked with, from either companies. Please filter your personal prejudices against certain companies for whatever personal encounters you had with them or who you work for. We are only interested to evaluate this based on sound scientific and engineering principles, we are not interested in your personal prejudices.

(edited by DarkSpirit.7046)

OData?

in API Development

Posted by: Killer Rhino.6794

Killer Rhino.6794

~shrug~

When I do a search for OData, which I had never heard of before reading this thread, almost all of the top results are from Microsoft oriented sites/projects — https://duckduckgo.com/?q=odata

The first interesting result that pertains to this conversation is a StackOverflow question — http://stackoverflow.com/questions/2458407/difference-between-odata-and-rest-web-services . The accepted answer should tell you why no one here is excited by your suggestion:

As Franci said, OData is based on Atom Pub. However, they have layered some functionality on top and unfortunately have ignored some of the REST constraints in the process.

The querying capability of an OData service requires you to construct URIs based on information that is not available, or linked to in the response. It is what REST people call out-of-band information and introduces hidden coupling between the client and server.

While the current API isn’t exactly transparent, it doesn’t bind you to using a specific technology (other than being able to parse text). OData is brining nothing useful to the table.

I haven’t addressed your insistence on “it also supports JSON” because there really isn’t any point. Why would it supporting JSON immediately make it a worthwhile change? JSON as an output format doesn’t make the added complexity of being able to get the output worth it.

I’m not “biased against technologies from Microsoft simply because [I] hate Microsoft.” But I’m certainly no fan of their style and won’t just accept using their solution when a simpler, more open one, is possible.

Man, you nailed it.

“Point was well made, and delivery was fast. A++++, would buy again!”

Creator of GW2Kit