Changes between Version 4 and Version 5 of Future/RESTfulWebServices


Ignore:
Timestamp:
03/19/08 22:06:29 (17 years ago)
Author:
jbirch
Comment:

Formatting

Legend:

Unmodified
Added
Removed
Modified

  • Future/RESTfulWebServices

    v4 v5  
    1111= Conventions =
    1212
    13 For now lets assume the URI: !http://example.org/mapguide/rest is the root of the !MapGuide RESTful web services. All subsequent URIs below will leave this part off and focus on resources and their representations.
     13All of the calls here assume a HOST header similar to "HOST: example.org".  As well, all requests would be located under /mapguide/rest but in this document we will assume that they start from the document root.
    1414
    1515Unless otherwise stated, you can assume that a GET returns the content of the resource, a POST creates a new resource from the HTTP body contents, a PUT replaces the contents of an existing resource with the contents of the HTTP body, and a DELETE removes the resource.  The HTTP contents returned for these requests is variable depending on what is requested, but proper HTTP response codes (200, 404, and many other relevant codes) must be issued to ensure correct behaviour of the clients.
    … …  
    7373
    7474{{{
     75  http://example.org/library/PathTo/Resource.FeatureSource
     76}}}
     77
     78Or, in an actual installation, as:
     79
     80{{{
    7581  http://example.org/mapguide/rest/library/PathTo/Resource.FeatureSource
    7682}}}
    7783
     84
    7885It is important to note that these will always be provided without hints to content type.
    7986
    … …  
    9198
    9299{{{
    93 GET
    94 .../library/MyStuff/Parcels.FeatureSource/content
     100GET /library/MyStuff/Parcels.FeatureSource/content
    95101}}}
    96102
    … …  
    101107
    102108{{{
    103 PUT
    104 .../library/MyStuff/Parcels.FeatureSource/header
     109PUT /library/MyStuff/Parcels.FeatureSource/header
    105110}}}
    106111
    … …  
    108113
    109114{{{
    110 POST
    111 .../library/MyStuff/Parcels.FeatureSource/data/<dataname>.<datatype>
     115POST /library/MyStuff/Parcels.FeatureSource/data/<dataname>.<datatype>
    112116}}}
    113117
    … …  
    117121
    118122{{{
    119 GET
    120 .../library/MyStuff?depth=<depth>&type=<resourcetype>
     123GET /library/MyStuff?depth=<depth>&type=<resourcetype>
    121124}}}
    122125
    … …  
    124127
    125128{{{
    126 GET
    127 .../library/MyStuff/Parcels.FeatureSource/data
     129GET /library/MyStuff/Parcels.FeatureSource/data
    128130}}}
    129131
    … …  
    131133
    132134{{{
    133 GET
    134 .../session/<uglysessionid>/Parcels.LayerDefinition
     135GET /session/<uglysessionid>/Parcels.LayerDefinition
    135136}}}
    136137
    … …  
    140141
    141142{{{
    142 POST
    143 .../services/CopyResource
     143POST /services/CopyResource
    144144Source=http://example.com/mapguide/rest/library/MyStuff/Parcels.FeatureSource
    145145Destination=http://example.com/mapguide/rest/library/MyStuff/ParcelsCopy.FeatureSource
    … …  
    150150Now this is where things start to get interesting. What alternate representations do we expose for Feature Sources to support the Feature Services API?
    151151
    152 
    153152''' (jb) QUESTION:  Again, I am somewhat concerned that we are introducing elements (schema, spatialcontexts, features) that the client has to just know about.  Is there any way that we can return an enumeration of these endpoints when the MyData.FeatureSource is requested?.'''
    154153
    … …  
    156155
    157156{{{
    158 GET
    159 .../library/MyStuff/MyData.FeatureSource/schema
     157GET /library/MyStuff/MyData.FeatureSource/schema
    160158}}}
    161159
    … …  
    163161
    164162{{{
    165 GET
    166 .../library/MyStuff/MyData.FeatureSource/schema/<schemaname>
    167 }}}
    168 
    169 {{{
    170 GET
    171 .../library/MyStuff/MyData.FeatureSource/schema/<schemaname>/<classname>
     163GET /library/MyStuff/MyData.FeatureSource/schema/<schemaname>
     164}}}
     165
     166{{{
     167GET /library/MyStuff/MyData.FeatureSource/schema/<schemaname>/<classname>
    172168}}}
    173169
    … …  
    175171
    176172{{{
    177 GET
    178 .../library/MyStuff/MyData.FeatureSource/spatialcontexts
     173GET /library/MyStuff/MyData.FeatureSource/spatialcontexts
    179174}}}
    180175
    … …  
    182177
    183178{{{
    184 GET
    185 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
     179GET /library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
    186180
    187181Optional Parameters:
    … …  
    197191
    198192{{{
    199 GET
    200 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>
     193GET /library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>
    201194}}}
    202195
    … …  
    204197
    205198{{{
    206 DELETE
    207 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>
     199DELETE /library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>
    208200}}}
    209201
    … …  
    211203
    212204{{{
    213 DELETE
    214 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
     205DELETE /library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
    215206
    216207Required Parameter:
    … …  
    223214
    224215{{{
    225 POST
    226 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
     216POST /library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
    227217}}}
    228218
    … …  
    230220
    231221{{{
    232 PUT
    233 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
     222PUT /library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
    234223
    235224Required Parameter:
    … …  
    237226}}}
    238227
    239 In both cases the HTTP request envelope must contain a property value collection that defines either the properties of the newly created feature or the properties to be updated and their new values. The collection could be in either JSON or XML format and an open question whether the URI should specify the expected type?
    240 
    241 ''' (jb) QUESTION:  Say what?'''
    242 
    243 [[BR]]
    244 [[BR]]
     228In both cases the HTTP request envelope must contain a property value collection that defines either the properties of the newly created feature or the properties to be updated and their new values. The collection could be in either JSON or XML format.
     229
     230''' (rb) QUESTION: whether the URI should specify the expected type? '''
     231
     232''' (jb) QUESTION: Say what?'''
     233
     234
    245235'''TBD''' - Still need to think about how to support other Feature Service operations
    246 [[BR]]
    247 [[BR]]
    248 [[BR]]
     236
    249237
    250238== Alternate Representations for Maps, Map Definitions, and Layer Definitions ==
    … …  
    255243
    256244{{{
    257 POST
    258 .../session/<uglysesssionid>/MyMap.Map
     245POST /session/<uglysesssionid>/MyMap.Map
    259246
    260247Required Parameters:
    … …  
    263250
    264251{{{
    265 POST
    266 .../session/<uglysesssionid>/MyMap.Map
     252POST /session/<uglysesssionid>/MyMap.Map
    267253
    268254Required Parameters:
    … …  
    274260
    275261{{{
    276 POST
    277 .../services/createmap
     262POST /services/createmap
    278263Required Parameters:
    279264  session=<uglysesssionid>
    … …  
    290275
    291276{{{
    292 GET
    293 .../session/<uglysesssionid>/MyMap.Map/image
     277GET /session/<uglysesssionid>/MyMap.Map/image
    294278
    295279Optional Parameters:
    … …  
    298282
    299283{{{
    300 POST
    301 .../session/<uglysesssionid>/MyMap.Map/image
     284POST /session/<uglysesssionid>/MyMap.Map/image
    302285
    303286Optional Parameters:
    … …  
    311294
    312295{{{
    313 GET
    314 .../session/<uglysesssionid>/MyMap.Map/overlayimage
     296GET /session/<uglysesssionid>/MyMap.Map/overlayimage
    315297
    316298Optional Parameters:
    … …  
    319301
    320302{{{
    321 POST
    322 .../session/<uglysesssionid>/MyMap.Map/overlayimage
     303POST /session/<uglysesssionid>/MyMap.Map/overlayimage
    323304
    324305Optional Parameters:
    … …  
    327308
    328309{{{
    329 GET
    330 .../library/MyStuff/MyMap.MapDefinition/basetileimage/<baselayergroupname>/<scaleindex>/<tilecolumn>,<tilerow>
    331 
     310GET /library/MyStuff/MyMap.MapDefinition/basetileimage/<baselayergroupname>/<scaleindex>/<tilecolumn>,<tilerow>
    332311}}}
    333312
    … …  
    336315''' (jb) COMMENT:  For the /basetileimage calls, it is critical that we support all standard HTTP caching headers.  This means checking state of the underlying tile; does this require new APIs for the tile service to return properties of the existing tile when not generating fresh? '''
    337316
    338 
    339317To build a cool client application, we need information about the map, the layers, the layer groups, etc. The next set of operations is designed to return an informational representation of map that can be used to create a compelling user interface.  These could be in JSON or XML.
    340318
    341319{{{
    342 GET
    343 .../session/<uglysesssionid>/MyMap.Map
    344 
    345 GET
    346 .../session/<uglysesssionid>/MyMap.Map/layers
    347 
    348 GET
    349 .../session/<uglysesssionid>/MyMap.Map/layers/<layername>
    350 
    351 GET
    352 .../session/<uglysesssionid>/MyMap.Map/layergroups
    353 
    354 GET
    355 .../session/<uglysesssionid>/MyMap.Map/layergroups/<layergroupname>
     320GET /session/<uglysesssionid>/MyMap.Map
     321
     322GET /session/<uglysesssionid>/MyMap.Map/layers
     323
     324GET /session/<uglysesssionid>/MyMap.Map/layers/<layername>
     325
     326GET /session/<uglysesssionid>/MyMap.Map/layergroups
     327
     328GET /session/<uglysesssionid>/MyMap.Map/layergroups/<layergroupname>
    356329}}}
    357330
    … …  
    359332
    360333{{{
    361 GET
    362 .../library/MyStuff/MyLayer.LayerDefinition/legendicon/<mapscale>/<geomtype>/<themecat>
     334GET /library/MyStuff/MyLayer.LayerDefinition/legendicon/<mapscale>/<geomtype>/<themecat>
    363335
    364336Optional Parameters:
    … …  
    370342
    371343{{{
    372 GET
    373 .../session/<uglysesssionid>/MyMap.Map/features
     344GET /session/<uglysesssionid>/MyMap.Map/features
    374345
    375346Optional (but highly recommended) Parameters:
    … …  
    384355''' (jb) COMMENT:  Some services have suggested storing the spatial filter feature as its own resource, and just refering to it in the GET.  This would prevent problems with overflowing the GET max size'''
    385356
    386 [[BR]]
    387 [[BR]]
     357
    388358'''TBD''' - Still need more stuff for adding layers dynamically, plotting to DWF, etc.
    389 [[BR]]
    390 [[BR]]
     359
     360
    391361''' (rb) Note: Within all of this the handling of selection is bugging me. We need to think about that some more and figure out what is the right way of handling selection RESTfully. '''
    392 [[BR]]
     362
    393363
    394364== Other Necessary Stuff ==
    … …  
    396366
    397367{{{
    398 POST
    399 .../session
     368POST /session
    400369}}}
    401370
    402 
    403 
    404371There is no required HTTP request envelope and the return envelope would simply contain the newly created session URI, e.g. http://somemgsite.org/mapguide/rest/session/<newuglysessionid>/ along with a 201 header.
    405372