| 263 | == API Method Examples (cont.): == |
| 264 | |
| 265 | An example of create_slice call would specify required options e.g.: |
| 266 | |
| 267 | { |
| 268 | |
| 269 | ‘fields’ : { |
| 270 | |
| 271 | “SLICE_NAME”: “TEST_SLICE”, |
| 272 | |
| 273 | “SLICE_DESCRIPTION”: “My Test Slice”, |
| 274 | |
| 275 | “SLICE_EMAIL”: myemail@geni.net, |
| 276 | |
| 277 | “PROJECT_URN”: “urn:publicid+IDN+this_sa+project+myproject” |
| 278 | |
| 279 | } |
| 280 | |
| 281 | } |
| 282 | |
| 283 | and receive a return dictionary looking like: |
| 284 | |
| 285 | { |
| 286 | |
| 287 | “SLICE_URN”: “urn:publicid+IDN+this.sa+slice+TESTSLICE”, |
| 288 | |
| 289 | “SLICE_UID”: “…”, |
| 290 | |
| 291 | “SLICE_NAME”: “TESTSLICE”, |
| 292 | |
| 293 | “SLICE_CREDENTIAL”: “.....”, |
| 294 | |
| 295 | “SLICE_DESCRIPTION”: “My Test Slice”, |
| 296 | |
| 297 | “PROJECT_URN”: “urn:publicid+IDN+this_sa+project+myproject”, |
| 298 | |
| 299 | “SLICE_EXPIRATION”: “2013-08-29T13:15:30Z”, |
| 300 | |
| 301 | “SLICE_EXPIRED”: “FALSE”, |
| 302 | |
| 303 | “SLICE_CREATION”: “2013-07-29T13:15:30Z”, |
| 304 | |
| 305 | “SLICE_EMAIL”: myemail@geni.net |
| 306 | |
| 307 | } |
| 308 | |
| 309 | == API Authentication == |
| 310 | |
| 311 | This document suggests that the Authentication required for the CH is implicit in the SSL protocol: the invoker of the call must have its cert and private key to have a valid SSL connection. Moreover, the cert must be signed by a member of the trust chain recognized by the CH. |
| 312 | |
| 313 | == Support for Speaks-for API Invocations == |
| 314 | |
| 315 | Best practices dictate that individuals should speak as themselves: that is, the entity on the other side of an SSL connection is the one referred to by the certificate on the connection. Obviously, people typically use tools or software interfaces to create these connections. When a tool is acting directly on a user’s desktop using the user’s key and cert with the user’s explicit permission, it may be acceptable to consider the tool as speaking as the user. But for many tools, the tool is acting on behalf of the user in invoking CH or AM API calls. In this case, it is important for the tool to not speak as the user but to speak for the user, and to have the service to whom the tool is speaking handle the authorization and accountability of this request accordingly. |
| 316 | |
| 317 | Accordingly, a Clearinghouse and associated Authorities should support speaks-for API transactions. These API transactions use the same signatures as the calls described in this document, with these enhancements: |
| 318 | - The user (spoken-for) URN provided as a ‘speaking-for’ option on the call |
| 319 | - The user’s certificate be provided as part of the credentials of the call |
| 320 | - The speaks-for credential: a statement signed by the user indicating that the tool has the right to speak for the user, possibly limited to a particular scope (e.g. slice, project, API call, time window). |