usage = HTTPUsage('', 'Create a new object. You must provide credentials for '
'this call to succeed.')
topLevel.addUsage(usage)
usage.resourceClass = ObjectsResource
usage.successCode = http.CREATED
apiDoc.addBadRequestPayload(usage)
apiDoc.addCannotRespondWithPayload(usage)
usage.addReturn(Return(apiDoc.UNAUTHORIZED,
'If valid credentials are not provided.'))
usage.addReturn(Return(
apiDoc.httpCode(usage.successCode),
'A new object was created without error.'))
requestPayload = JSONPayload()
requestPayload.addField(PayloadField(
aboutArg,
unicode,
"""The value for the %(about)s tag. If you do not want an
an %(about)s tag on this object, omit this field.
""" %
{'about': apiDoc.ABOUT},
mandatory=False))
usage.addRequestPayload(requestPayload)
responsePayload = JSONPayload()
apiDoc.UNAUTHORIZED, 'If the requesting user does not have ' +
apiDoc.CREATE + ' permission on the parent namespace.'))
usage.addReturn(
Return(
apiDoc.BAD_REQUEST,
'If the full path of the new namespace is too long.' +
' The current maximum path length is ' + str(paths.maxPathLength) +
' characters.'))
apiDoc.addBadRequestPayload(usage)
apiDoc.addCannotRespondWithPayload(usage)
usage.addReturn(
Return(apiDoc.httpCode(usage.successCode),
'If the namespace is created successfully.'))
requestPayload = JSONPayload()
requestPayload.addField(
PayloadField('name', unicode, 'The name of the new namespace.'))
requestPayload.addField(
PayloadField('description',
unicode,
'A description of the namespace.',
mayBeNone=True))
usage.addRequestPayload(requestPayload)
responsePayload = JSONPayload()
responsePayload.addField(
PayloadField(
usage.addReturn(
Return(
apiDoc.UNAUTHORIZED,
'If the requesting user does not have ' + apiDoc.READ +
' permission on a tag whose value is needed to satisfy the query.'))
usage.addReturn(
Return(
apiDoc.UNAUTHORIZED, 'If the requesting user does not have ' +
apiDoc.READ + ' permission on a tag whose value is requested.'))
apiDoc.addCannotRespondWithPayload(usage)
usage.addReturn(
Return(apiDoc.httpCode(usage.successCode), 'No error occurred.'))
responsePayload = JSONPayload()
responsePayload.addField(
PayloadField(
resultsKey,
dict,
# TODO: describe this better, point to as-implemented version of
# the original spec/draft.
'''A dictionary containing information about the requested tag values
on objects that match the query. See example below.'''))
usage.addResponsePayload(responsePayload)
# TODO: put a real query into the URI.
request = ('GET /%(toplevel)s?%(query)s=mike%%2Frating>5&'
apiDoc.BAD_REQUEST,
"""If the username is unacceptable due to syntax. Usernames may
contain only letters (according to the Unicode standard), digits,
underscores, hyphens, colons, and periods."""))
usage.addReturn(Return(
apiDoc.BAD_REQUEST,
'If the username is too long. The maximum length of a username is ' +
str(users.maxUsernameLength) + ' characters.'))
apiDoc.addBadRequestPayload(usage)
apiDoc.addCannotRespondWithPayload(usage)
usage.addReturn(Return(
apiDoc.httpCode(usage.successCode),
'If the user is created successfully.'))
requestPayload = JSONPayload()
requestPayload.addField(PayloadField(
'username', unicode, 'The Fluidinfo username for the new user.'))
requestPayload.addField(PayloadField(
'name', unicode, 'The real-world name of the new user.', False))
requestPayload.addField(PayloadField(
'password', unicode, 'The password for the new user.'))
requestPayload.addField(PayloadField(
'email', unicode, 'The email address of the new user.'))
usage.addRequestPayload(requestPayload)
responsePayload = JSONPayload()
responsePayload.addField(PayloadField(