appdotnet / api-spec

App.net API Documentation is on the web at https://developers.app.net. Source for these docs is in the new-docs branch here. Please use the issue tracker and submit pull requests! Help us build the real-time social service where users and developers come first, not advertisers.
https://developers.app.net
950 stars 98 forks source link

Move "Type" in annotations to be a key #184

Closed edent closed 12 years ago

edent commented 12 years ago

I would like annotations to look like this:

"annotations" : { 
    "com.example.foo" : { "ip" : "8.8.8.8" },
    "net.app.core.geolocation" : { 
        "latitude" : 50.555,
        "longitude" : 12.345000000000001
    }
} 

This would mean that we could do

$annotations["net.app.core.geolocation"]

Rather than

    foreach($status['annotations'] as $annotation) 
    {
        if ($annotation['type'] == "net.app.core.geolocation")
        {
            $lat = $annotation['value']['latitude'];
            $long = $annotation['value']['longitude'];
        }
    }
kosso commented 12 years ago

While I agree and like what you're thinking, I think it could maybe cause issues due to the lack of 'type' or 'value' properties (though they are intrinsically implied). Something tells me people could do evil things. Or something.

beccadax commented 12 years ago

So far, the App.net API always uses JSON objects as objects with a fixed set of properties, not dictionaries/hashes with keys that vary from one place to another. What you're suggesting simply isn't the style of the App.net API.

(Remember, you can always rearrange the annotations into whatever data structure is most convenient for you.)

edent commented 12 years ago

Forgive my ignorance - is there a good technical reason why that is the case? Are the specific advantages to do it that way?

mattflaschen commented 12 years ago

That's not valid JSON, and I'm not sure what you're intending. However, besides the fixed schema issue, it seems like this would not allow two annotations with the same type. Some annotations may want to allow this; for instance a post about two places you were today might have two geo points.

edent commented 12 years ago

@mattflaschen sorry, have updated it - that's what I get for mixing PHP & JSON :-) Hope that makes it clearer.

However, your point about having duplicate annotations in the same post is an interesting one.

berg commented 12 years ago

Basically what @mattflaschen said: the point is to allow multiple annotations of the same type in the same post. I don't anticipate this changing anytime soon, so I'm going to close this issue.