API questions

[k0s]

I am trying to learn the open311 API and have a few questions
regarding some of its intent:

* API Key: the URL schema given is `http://api.dc.gov/api_name/
version/method.format?apikey=YOUR_KEY&params` , what is the reason for
the api key? Is this just a substitute for auth while open311 is in
the "beta" phase? will this eventually be replaced by auth?

* for the application registration, http://api.dc.gov/key , it wants
an application URL. Does this mean I shouldn't register for a key
until I have the application deployed somewhere? Then give it some
base URL equivalent to http://api.dc.gov/myappname/beta? Will you
forward requests to my service? Or...?

* can the `version` part of the URL be anything? what should it be?

* is there a reason for the 'meta_' prefix of 'meta_getTypesList' and
'meta_getTypeDefinition'? is there a reason for it, or just to make
it look more semantic?

* looking at the JSON from `http://api.dc.gov/open311/v1/
meta_getTypesList.json`:

"""
{"servicetype": [{"servicetype": "Traffic Signals"}, {"servicecode":
"S0436"}]}, {"servicetype": [{"servicetype": "Traffic Signs"},
{"servicecode": "S0376"}]}, {"servicetype": [{"servicetype": "Trash
Collection"}, {"servicecode": "S0441"}]}, {"servicetype":
[{"servicetype": "Tree Emergency"}, {"servicecode": "S0457"}]},
{"servicetype": [{"servicetype": "Tree Maintenance"}, {"servicecode":
"S0456"}]}, {"servicetype": [{"servicetype": "Tree Planting"},
{"servicecode": "S04TP"}]},
"""

My first question is: why a list of hashes all with the same key? I
don't know, maybe there's a good reason.

My second question is: why a service code? Is anything gained by
this? To me it just adds obscurity.

In general, is the JSON from the examples supposed to be what the JSON
looks like? Or is this flexible? If it is canonical, then maybe it
should be documented.

* for the `meta_TypeDefinition` example,
http://api.dc.gov/open311/v1/meta_getTypeDefinition.json?servicecode=S0000
, The format for fields is only implicit in the example, which I find
disturbing. Again, the format is a bit different from what I
expected. Maybe its worth documenting what this should look like? I
don't know if putting such HTML-ish verbosing like {"type":
"DropDown "} is a good idea. Thoughts?

* for the `submit` method, should the application store its own
data? or should it interface with some back-end store that already
exists? (i guess this question is also important for the `get`
method)

Thanks! Sorry for the barrage.

Jeff

[k0s]

>  * for the `submit` method, should the application store its own
> data?  or should it interface with some back-end store that already
> exists?  (i guess this question is also important for the `get`
> method)

Sorry, maybe this is unclear. My question is, do the apps implement
the storage themselves? Or do they interface with some existing DB?
I'm guessing they store themselves, but I woud like some
clarification.

[jeff blasius]

I'm not an expert, but I think I can help with some of these... Some
items can be answered by just saying that the api is in beta and might
have some wrinkles. Hopefully they'll iron them out and increment the
version :)

On Jun 24, 3:18 pm, k0s <k0sc...@gmail.com> wrote:
> I am trying to learn the open311 API and have a few questions
> regarding some of its intent:
>
>  * API Key:  the URL schema given is `http://api.dc.gov/api_name/
> version/method.format?apikey=YOUR_KEY&params` , what is the reason for
> the api key? Is this just a substitute for auth while open311 is in
> the "beta" phase? will this eventually be replaced by auth?

I believe the api key is DC's form of authentication. Regardless, the
api calls function without needing to include this key. Presumably the
key will be required once the api is out of beta.

>
>  * for the application registration,http://api.dc.gov/key, it wants

> an application URL.  Does this mean I shouldn't register for a key
> until I have the application deployed somewhere? Then give it some

> base URL equivalent tohttp://api.dc.gov/myappname/beta? Will you

> forward requests to my service?  Or...?

You can register for a key and include it in your code, but like I
said above, it is not necessary right now.

>
>  * can the `version` part of the URL be anything?  what should it be?

Version is "v1" right now.

>
>  * is there a reason for the 'meta_' prefix of 'meta_getTypesList' and
> 'meta_getTypeDefinition'?  is there a reason for it, or just to make
> it look more semantic?
>
>  * looking at the JSON from `http://api.dc.gov/open311/v1/
> meta_getTypesList.json`:
>
> """
> {"servicetype": [{"servicetype": "Traffic Signals"}, {"servicecode":
> "S0436"}]}, {"servicetype": [{"servicetype": "Traffic Signs"},
> {"servicecode": "S0376"}]}, {"servicetype": [{"servicetype": "Trash
> Collection"}, {"servicecode": "S0441"}]}, {"servicetype":
> [{"servicetype": "Tree Emergency"}, {"servicecode": "S0457"}]},
> {"servicetype": [{"servicetype": "Tree Maintenance"}, {"servicecode":
> "S0456"}]}, {"servicetype": [{"servicetype": "Tree Planting"},
> {"servicecode": "S04TP"}]},
> """
>
> My first question is:  why a list of hashes all with the same key?  I
> don't know, maybe there's a good reason.
>
> My second question is:  why a service code?  Is anything gained by
> this?  To me it just adds obscurity.
>
> In general, is the JSON from the examples supposed to be what the JSON
> looks like?  Or is this flexible?  If it is canonical, then maybe it
> should be documented.
>

>  * for the `meta_TypeDefinition` example,http://api.dc.gov/open311/v1/meta_getTypeDefinition.json?servicecode=...

> , The format for fields is only implicit in the example, which I find
> disturbing.  Again, the format is a bit different from what I
> expected.  Maybe its worth documenting what this should look like?  I
> don't know if putting such HTML-ish verbosing like  {"type":
> "DropDown          "} is a good idea.  Thoughts?
>
>  * for the `submit` method, should the application store its own
> data?  or should it interface with some back-end store that already
> exists?  (i guess this question is also important for the `get`
> method)

I haven't heard otherwise, so the application should store both the
service request token then the service request id. You'll probably
want to store data entered to the system too, but that's up to you.

-jeff