Subject: Re: [scim] API comments section 3.5 to end

From: Phil Hunt <[email-masked]>
Date: Fri, 1 Aug 2014 14:32:12 -0700

Hi all,

There are some important considerations here. Please see commend below:

Phil

@independentid
www.independentid.com
[email-masked]

On Jul 31, 2014, at 8:13 PM, Kelly Grizzle <[email-masked]> wrote:

> Last set of comments for the API doc.
>  
> > 3.5  status  A complex type that contains information about the success
> >              or failure of one operation within the bulk job.  REQUIRED in a
> >              response.
> > 
> >              code  The HTTP response code that would have been returned if a
> >                 a single HTTP request would have been used.  REQUIRED.
> > 
> >              description  A human readable error message.  REQUIRED when an
> >                 error occurred.
>  
> Should the bulk response status attribute be updated to be more in line with the updated error response (status, scimType, and detail sub-attributes)?

I am going to suggest we change “status” back to correspond with HTTP Status.

We should also have a “response” block which contains the optional payload response. In the case of an error condition, the normal http response body is included in “response” which would include the error JSON message e.g.
  “response”:{
     "schemas": ["urn:scim:api:messages:2.0:Error"],
     "scimType":"mutability"
     "detail":"Attribute 'id' is readOnly",
     "status":"400"
   },
   “status”:”400"
 
===> Question. Do we want to make the server give the normal JSON responses for all operations and provide them in response? E.g. after a POST show the record as processed by the service provider.

>  
>  
> > 3.5    If a bulk job is processed successfully the HTTP response code 200 OK
> >        MUST be returned, otherwise an appropriate HTTP error code MUST be
> >        returned.
>  
> A 200 is returned even if some of the operations failed, correct?  Might be worth clarifying.

Yes.  I think so. The only reason not to return 200 would be a syntax error in the request, or other fatal error condition.

In the context of a bulk request, an individual transaction failure is indicated within the status/response for the operation.
>  
>  
> > 3.5 The client MAY override
> >     this behavior by specifying a value for failOnErrors attribute.
>  
> Change to "for the failOnErrors attribute”.

Ok.
>  
>  
> > 3.5 A location attribute that includes the
> >     resource's end point MUST be returned for all operations excluding
> >     failed POSTs.
>  
> Typo.  Change "end point" to "endpoint".
>  
Ok
>  
> > 3.5  The following example shows how to add, update, and remove a user.
> >      ...
> >      The service provider returns the following response.
> >      ...
> >         {
> >             "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
> >             "method": "POST",
> >             "bulkId": "qwerty",
> >             "version": "W\/\"oY4m4wn58tkVjJxK\"",
> >             "status": {
> >                 "code": "201"
> >             }
> >         },
>  
> The text above says the following regarding creating a new resource:
>  
>   the service provider MUST return the same bulkId together with the newly
>   created resource.
>  
> It seems like the example response should include the full resource.  Would this fit in the "data" sub-attribute?  If so, the description of the "data" sub-attribute should be changed to indicate this.  Same comment for other bulk examples that contain POSTs.

See comment above.
>  
>  
> > 3.5  The following example creates a User with the userName 'Alice' and a
> >      Group with the displayName 'Tour Guides' with Alice as a member.
> >      ...
> >            "members": [
> >             {
> >               "type": "user",
> >               "value": "bulkId:qwerty"
> >             }
> >           ]
>  
> The type should be "User" since the canonical values for type on member are capitalized (see schema in section 11.7 of schemas draft).
ok
>  
>  
> > 3.5            "members": [
> >               {
> >                 "type": "group",
>  
> Same comment as above ... need to capitalize "Group".
>  
> 
ok
>  
> > 3.5  The following example the client sent a request exceeding the service
> >      provider's max payload size of 1 megabyte.
> >      ...
> >      HTTP/1.1 413 Request Entity Too Large
> >      Content-Type: application/scim+json
> >      Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8
>  
> This response includes a Location header with a unique ID.  Do bulk requests have unique IDs and locations?  If not, the location should be removed

I think the spec should be ambiguous on the point and thus location could be removed.
>  
>  
> > 3.6 MAY specify the desired response data
> >     format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g.,
> >     "Accept: application/scim+json" or via URI suffix; e.g.,
> > 
> >      GET /Users/2819c223-7f76-453a-919d-413861904646.scim
>  
> It seems like we shouldn't need to support URI suffixes anymore since JSON is the only supported format.

My approach here was to comply with mime type registration.  In reality some may choose to implement other formats like XML even though we haven’t specified it.  Or, a future SCIM extension might call for a new format.  This sets the foundation.

I think it is fair to say JSON is the default (and currently only supported method).

Will try to think about the language a bit and try to get a better balance.

>  
>  
> > 3.7   The defaut attribute set are those attributes whose schema have
>  
> Typo on "defaut".
>  
> 
Got it
>  
> > 3.7     GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
> >         ...
> >         Accept: application/json
> >         ...
> >         HTTP/1.1 200 OK
> >         Content-Type: application/json
>  
> This example uses application/json for the Accept and Content-Type headers.  Should change this to application/scim+json.
>  
>  
> 
OK
> > 3.10  The following attributes are defined inclusion in a SCIM error response
> >       using a JSON body:
>  
> Not sure what the text is supposed to be here, but "defined inclusion" doesn't make sense to me.  Maybe “The following attributes are included in a SCIM error response using a JSON body”?
>  
> 
Should be:

“The following attributes are defined for a SCIM error response…."
>  
> > 3.10  status
> >         The HTTP status value (e.g. 400).  REQUIRED
>  
> We should indicate that this is an integer.
> 
Changed this to point to Section 6, RFC7231  (a 3 digit Integer).
>  
> > 3.10    Implementers SHOULD handle the identified errors as described below
>  
> 307 and 308 statuses are not really errors.  Should they be included here?

Agreed. I’ve re-worked the title of the section and the text to reflect that is it SCIM HTTP Status Code Handling
>  
>  
> > 3.10  tooMany   a filter such as "userName eq "*"" would return all entries with a "userName"
>  
> The wildcard operator is not supported.  This filter should be "userName pr”.

d’oh - fixed
>  
>  
> > 3.12    Content-Type:  application/json
>  
> Examples in this section are not using application/scim+json for Content-Type.
>  
>  
> > 6.2  A detialed error,
> >      "confidential_restricted" may be returned indicating the request must
> >      be submitted using POST.
>  
> Typo on "detialed".  Also, should this error code be made into a scimType and use the camelCase convention used for other scimTypes?  The example in this section could be rewritten as:
>  
>    {
>      "schemas": ["urn:scim:api:messages:2.0:Error"],
>      "scimType":"confidentialRestricted"
>      "detail":"Query filter involving 'name' is restricted or confidential",
>      "status":403
>    }
>  
> 
check
>  
> > 7.1 SCIM services may be offered by web applications wishin to offer
>  
> Typo on "wishin”.

I’m wishin’ I was done!
>  
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim