Mapping the API

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

Ahoy there.

I’m currently trying to wrap my head around the GW2 API before I can even begin to use it. In the process, picked away at data pulled from the item details JSON and tried to lay out all I’ve found in a manner that might make it easier to understand. Largely for my own benefit, but it might be of use for others (if they can even make sense of it) o.O

You can find my efforts so far here: Clicky

Everything is indented to show what’s nested where. Hopefully it’s understandable and makes some semblance of sense. There are a few bits of data that are incomplete in there (pretty sure there are more attributes, for example), and any gap-filling would be appreciated.

=faceplants hard and falls asleep at his desk= -_-’

Mapping the API

in API Development

Posted by: smiley.1438

smiley.1438

Great work! Thanks!

Mapping the API

in API Development

Posted by: Dr Ishmael.9685

Dr Ishmael.9685

In a crazy twist of fate, I did the exact same thing and posted it on the wiki at API/item details (link fixed) before I saw Pointless’s page. It would probably be a good idea for someone to compare our two versions to see if there are any discrepancies.

(edited by Dr Ishmael.9685)

Mapping the API

in API Development

Posted by: smiley.1438

smiley.1438

Your link points to the gw1 wiki

http://wiki.guildwars2.com/wiki/API/item_details <- correct link

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

O_O

I’ve had a quick glance over yours. I didn’t think to split out the shared elements into a separate code block (which might have spared me some hassle, really) and I’ve noticed you’d commented that the ID numbers were ints as well. I had chosen not to do that in my version because, unless I’m unaware of something, there’s not really any reason to convert them, is there? I probably should have anyway. Fail on my part.

And clearly, my use of terminology is pretty sloppy too. :\

Mapping the API

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

Here is an obvious question: Shouldn’t this documentation be provided by ArenaNet for the usage of their api?

Note: Legendary is missing from rarity.

(edited by DarkSpirit.7046)

Mapping the API

in API Development

Posted by: Rawrfaec.6412

Rawrfaec.6412

I had chosen not to do that in my version because, unless I’m unaware of something, there’s not really any reason to convert them, is there?

Not really, no. Especially if you want a uniform interface. However, knowing they’re integers behind the scenes can be valuable contextual knowledge (you could choose to convert them if you wanted to, and it will be well-defined).

It becomes important because there are discrepancies between the APIs and although we’re expecting an item ID to a number it would be factually incorrect to say that they are for for instance the item detail API. A statically typed language would throw a fit.

(edited by Rawrfaec.6412)

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

Note: Legendary is missing from rarity.

Added. That, and “Junk” x_X
Thanks for that.

Here is an obvious question: Shouldn’t this documentation be provided by ArenaNet for the usage of their api?

I’d be inclined to agree with you. Seems a little odd to just toss it out there without providing some info on how the data is structured.

I had chosen not to do that in my version because, unless I’m unaware of something, there’s not really any reason to convert them, is there?

Not really, no. Especially if you want a uniform interface. However, knowing they’re integers behind the scenes can be valuable contextual knowledge (you could choose to convert them if you wanted to, and it will be well-defined).

That is a good point. o_O

(edited by The Pointless.3869)

Mapping the API

in API Development

Posted by: zeeZ.5713

zeeZ.5713

Here is an obvious question: Shouldn’t this documentation be provided by ArenaNet for the usage of their api?

I’d be inclined to agree with you. Seems a little odd to just toss it out there without providing some

Doesn’t seem odd to me. They’re just testing the waters, and this is what they got. They just throw it out there and see what we do with it, spending the time on readying new shinies for us.

Documenting would be something to do once the stuff is out there proper and more or less stable. We’ve got smart guys here, we can figure it out :P Maybe that’s what they’re counting on, hoping it’s well documented on the wikis by the community before they have to even lift a finger

Mapping the API

in API Development

Posted by: Dr Ishmael.9685

Dr Ishmael.9685

O_O

I’ve noticed you’d commented that the ID numbers were ints as well. I had chosen not to do that in my version because, unless I’m unaware of something, there’s not really any reason to convert them, is there?

If you ever wanted to sort items by ID, it wold be necessary depending on your coding language. Perl, for example, is smart enough to convert numeric strings to integers automatically and return a numeric sort, but other languages will just return a string sort: 1, 10, 100, 101, 102, 11, 2, etc. Not that sorting by ID is really meaningful, but I’m sure some people would find reasons to do so.

And clearly, my use of terminology is pretty sloppy too. :\

I wouldn’t be so quick to criticize yourself there, I’m not really certain of the proper jargon for JSON myself, so I just used the terms I’m familiar with (list vs array, for example).

Mapping the API

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

Here is an obvious question: Shouldn’t this documentation be provided by ArenaNet for the usage of their api?

I’d be inclined to agree with you. Seems a little odd to just toss it out there without providing some

Doesn’t seem odd to me. They’re just testing the waters, and this is what they got. They just throw it out there and see what we do with it, spending the time on readying new shinies for us.

Documenting would be something to do once the stuff is out there proper and more or less stable. We’ve got smart guys here, we can figure it out :P Maybe that’s what they’re counting on, hoping it’s well documented on the wikis by the community before they have to even lift a finger

The problem with that is the risk of breakage of apps that are written against the api. And the developers may not even know about it beforehand. What if they remove/rename/add some fields in the next game update? How easy it is to track the changes?

Granted that this is still beta and subject to change but I would expect no less from ArenaNet after release. All these should be properly managed in an officially released api by ArenaNet, at least that would be the expectation from a professional developer.

Preferably, they should at least document the expected enums now so we can help them review them at this stage. Reverse engineering the specs from the data can give wrong results. For example, maybe some of the flags are missing from their items. We know that legendary is missing but we may not know all the flags or some other fields that are suppose to be there but are not.

(edited by DarkSpirit.7046)

Mapping the API

in API Development

Posted by: Ruhrpottpatriot.7293

Ruhrpottpatriot.7293

A great KB, I was trying to get all the item flags, restrictions, etc. for the GW2.Net implementation but there were so many. Now I can drop those kitten strings an put in Enumerables. Makes things so much easier.

On the topic of Item Ids as strings or ints: While it may be beneficial for speed (but really, who cares about that speed advantage? Even if it’s that “obvious”.), the sorting via int can come in handy.

We at GW2.Net do a split approach (as the .Net framework does not support automatic conversion from string to int, for good reasons). The obvious integers are handled as ints the rest as a GUID. The only “problem” are the match Ids which have an “x-y” format, but that’s just a mild annoyance.

Administrator of GW2.NET: GitHub , Forum , NuGet

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

Hmm, picking apart WvW data, I’m realising that it may be more imperative to make it clear where the cases of integer values as strings are than I thought, and not just for sorting purposes (which I do agree makes sense, by the way ).

“matches.json” is returning the world IDs of each belligerent as true integers, where other JSONs return world IDs as strings.

Similarly, “match_details.json” returns objective IDs as true ints as well, but again, in the objective names JSON, that’s returned as a string.

Boy, did I almost fall backside over breast with that one. O___O’

[EDIT] Added recipes, events and WvW. If I’ve made a total screwup job of those, feel free to perform the second stage of the fish slapping dance on me.

[EDIT EDIT] And I will take some time out some time this week to compare mine and Dr. Ishmael’s for discrepancies. At the moment I don’t feel too awake to do an adequate job of it.

(edited by The Pointless.3869)

Mapping the API

in API Development

Posted by: Ruhrpottpatriot.7293

Ruhrpottpatriot.7293

Looking over it right now. If you screwed up you have to do this:
https://www.youtube.com/watch?feature=player_detailpage&v=p5Fi4FZGi98#t=29s

Administrator of GW2.NET: GitHub , Forum , NuGet

Mapping the API

in API Development

Posted by: DarkSpirit.7046

DarkSpirit.7046

Missing a weapon subtype enum, “TwoHandedToy”.

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

Missing a weapon subtype enum, “TwoHandedToy”.

Who’s version? It seems to be there on mine (unless I’m being an idiot and looking in the wrong place, which wouldn’t be the first time x_X).

Mapping the API

in API Development

Posted by: Dr Ishmael.9685

Dr Ishmael.9685

Missing a weapon subtype enum, “TwoHandedToy”.

Completely overlooked those. Fixed.

Mapping the API

in API Development

Posted by: Ruhrpottpatriot.7293

Ruhrpottpatriot.7293

You should include “Booze” into the list of consumable types.

Administrator of GW2.NET: GitHub , Forum , NuGet

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

You should include “Booze” into the list of consumable types.

Done.
I might get some time this week to look at the new changes, too. Hopefully.

Mapping the API

in API Development

Posted by: Ruhrpottpatriot.7293

Ruhrpottpatriot.7293

Here is the colours object. I formatted the first and last expression and deleted the ones in the middle.



{
	"colors":
	{
		"1231":
		{
			"name":"Glacial Teal",
			"cloth":
			{
				"brightness":27,
				"contrast":1.83594,
				"hue":175,
				"saturation":0.117188,
				"lightness":0.78125
			},
			"leather":
			{
				"brightness":32,
				"contrast":1.83594,
				"hue":175,
				"saturation":0.0976563,
				"lightness":0.78125
			},
			"metal":
			{
				"brightness":32,
				"contrast":1.99219,
				"hue":175,
				"saturation":0.078125,
				"lightness":0.917969
			}
		},
		// additional colours go here here
		"1221":
		{
			"name":"Key Lime",
			"default":
			{
				"brightness":2,
				"contrast":1.09375,
				"hue":130,
				"saturation":0.78125,
				"lightness":0.996094
			}
		}
	}
}
Administrator of GW2.NET: GitHub , Forum , NuGet

Mapping the API

in API Development

Posted by: Ruhrpottpatriot.7293

Ruhrpottpatriot.7293

Here is a sample guild without emblem flags I will post the flags further below:


{
	"guild_id": "FBEACB6E-975B-4E10-9E52-B4E140F1C3B8",
	"guild_name": "GaiscĂ­och",
	"tag": "GSCH",
	"emblem": {
		"background_id": 1,
		"foreground_id": 33,
		"flags": [],
		"background_color_id": 473,
		"foreground_primary_color_id": 617,
		"foreground_secondary_color_id": 443
	}
}

Administrator of GW2.NET: GitHub , Forum , NuGet

Mapping the API

in API Development

Posted by: The Pointless.3869

The Pointless.3869

Hullo,

Popping my head in after disappearing for a few. College conquered all else. I’ve noticed there’s been a fair few updates to the API as well. o_O

Has anyone else been working to map those out at all? If not, I can make a (re)start at the weekend, I think. I hope.