def _addCommonGetTagProperties(usage, category):
possibleActions = ', '.join(permissions.actionsByCategory[category])
usage.addArgument(
Argument(actionArg,
"""The action whose permissions information is
sought. Possible values are: """ + possibleActions + '.',
'string',
mandatory=True))
apiDoc.addMissingIntermediateNs(usage)
apiDoc.addNoSuchTag(usage)
apiDoc.addNeedTagPermOrAdmin(usage, apiDoc.CONTROL)
usage.addReturn(
Return(apiDoc.BAD_REQUEST,
'If the %s argument is missing or invalid.' % actionArg))
apiDoc.addCannotRespondWithPayload(usage)
apiDoc.addOkOtherwise(usage)
responsePayload = JSONPayload()
responsePayload.addField(
PayloadField('policy', unicode,
"""The policy (either 'open' or 'closed')."""))
responsePayload.addField(
PayloadField(
'exceptions',
list,
'The names of the users who are exceptions to the policy.',
listType=unicode))
usage.addResponsePayload(responsePayload)
def _addCommonPutTagProperties(usage, category):
possibleActions = ', '.join(permissions.actionsByCategory[category])
usage.addArgument(
Argument(actionArg,
"""The action whose permissions information is
to be updated. Possible values are: """ + possibleActions + '.',
'string',
mandatory=True))
apiDoc.addMissingIntermediateNs(usage)
apiDoc.addNoSuchTag(usage)
apiDoc.addNeedTagPermOrAdmin(usage, apiDoc.CONTROL)
apiDoc.addUnknownExceptionUser(usage)
usage.addReturn(
Return(
apiDoc.BAD_REQUEST, 'If the policy is not %r or %r.' %
(permissions.OPEN, permissions.CLOSED)))
usage.addReturn(
Return(apiDoc.BAD_REQUEST,
'If the %s argument is missing or invalid.' % actionArg))
apiDoc.addBadRequestPayload(usage)
usage.addReturn(
Return(apiDoc.NO_CONTENT, 'If permissions are changed successfully.'))
requestPayload = JSONPayload()
requestPayload.addField(
PayloadField(
'policy', unicode, 'The policy (either %r or %r).' %
(permissions.OPEN, permissions.CLOSED)))
requestPayload.addField(
PayloadField(
'exceptions',
list,
'The names of the users who are exceptions to the policy.',
listType=unicode))
usage.addRequestPayload(requestPayload)
def addNoSuchProfile(usage):
usage.addReturn(
Return(NOT_FOUND,
"If the requested profile does not exist."))
def addNoSuchTag(usage):
usage.addReturn(
Return(NOT_FOUND,
"If the tag does not exist."))
def addNoSuchNs(usage):
usage.addReturn(
Return(NOT_FOUND,
"If the namespace does not exist."))
def addUserNotFound(usage):
usage.addReturn(
Return(NOT_FOUND,
"If the user does not exist."))
def addNeedAdmin(usage, perm):
usage.addReturn(
Return(UNAUTHORIZED,
"""If the requesting user does not have """ + perm +
""" permission on the relevant system tag."""))
def addCannotRespondWithPayload(usage):
usage.addReturn(Return(
BAD_REQUEST,
'''An error with the request makes it impossible to respond. <a
href="http://doc.fluidinfo.com/fluidDB/api/'''
'''http.html#bad-request">More details</a>.'''))
given about value. If there is already a Fluidinfo object whose
''' + apiDoc.ABOUT_TAG + ''' tag has the given value, the returned
object id will be that of the pre-existing object. In this call, and
all others with an about value in the URI, you must convert
your about value to UTF-8 and then
<a href="http://en.wikipedia.org/wiki/Percent-encoding">
percent-encode</a> it before adding it to the request URI. You must
provide valid credentials for this call to succeed.
For an example see the PUT request, below.'''))
topLevel.addUsage(usage)
usage.resourceClass = AboutObjectResource
usage.successCode = http.CREATED
usage.addReturn(
Return(apiDoc.BAD_REQUEST,
'The ' + apiDoc.ABOUTSTR + ' argument was not valid UTF-8.'))
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.'))
responsePayload = JSONPayload()
responsePayload.addField(
PayloadField('id', unicode, 'The id of the new object.'))
"username" : "mike",
"value" : "I had to annotate my own tweet about annotating tweets."
},
{ "about" : "http://www.sublimetext.com/",
"id" : "362f95bd-5429-4a3d-90f7-576860ea7bac",
"tag" : "ceronman/comment",
"updated-at" : "2012-02-22T15:00:16.957497",
"username" : "ceronman",
"value" : "Very cool text editor."
}]""")
description = dedent("""
Retrieve information about recent values on objects followed by bob.""")
usage.addExample(HTTPExample(request, response, description))
usage.addReturn(Return(apiDoc.BAD_REQUEST, 'If no query is given.'))
usage.addReturn(
Return(apiDoc.BAD_REQUEST, 'The query string was not valid UTF-8.'))
usage.addReturn(
Return(apiDoc.BAD_REQUEST, 'If the query string could not be parsed.'))
usage.addReturn(
Return(apiDoc.BAD_REQUEST, 'If the query returns to many objects.'))
usage.addReturn(
Return(
apiDoc.NOT_FOUND, 'If one or more of the tags or namespaces present '
'in the query do not exist.'))
usage.addReturn(
Return(
apiDoc.UNAUTHORIZED, 'If the user does not have ' + apiDoc.READ +
' permission on a tag whose value is needed '
'to satisfy the query.'))
topLevel = HTTPTopLevel(httpUserCategoryName, 'POST')
topLevel.adminOnly = True
registry.register(topLevel)
# --- POST /users ---------------------------------------------------------
usage = HTTPUsage('', 'Create a new user.')
usage.adminOnly = True
usage.resourceClass = UsersResource
usage.successCode = http.CREATED
topLevel.addUsage(usage)
apiDoc.addNeedAdmin(usage, apiDoc.CREATE)
usage.addReturn(Return(
apiDoc.PRECONDITION_FAILED,
'If the user already exists.'))
usage.addReturn(Return(
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)
PayloadField('indexed', bool,
'Whether or not tag values should be indexed.'))
usage.addRequestPayload(requestPayload)
responsePayload = JSONPayload()
responsePayload.addField(
PayloadField('id', unicode,
'The id of the object that corresponds to the new tag.'))
responsePayload.addField(
PayloadField('URI', unicode, 'The URI of the new object.'))
usage.addResponsePayload(responsePayload)
usage.addReturn(
Return(
apiDoc.NOT_FOUND,
'If the containing namespace or an intermediate namespace '
"does not exist and you do not have permission to create it."))
usage.addReturn(
Return(
apiDoc.UNAUTHORIZED, 'If the user does not have ' + apiDoc.CREATE +
' permission on the containing (i.e., deepest) namespace.'))
usage.addReturn(
Return(apiDoc.PRECONDITION_FAILED, "If the tag already exists."))
usage.addReturn(
Return(
apiDoc.BAD_REQUEST, 'If the full path of the new tag is too long.' +
' The current maximum path length is ' + str(paths.maxPathLength) +
' characters.'))
# --- POST /objects -------------------------------------------------------
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)
def addOkOtherwise(usage):
usage.addReturn(Return(OK, "No error."))
usage = HTTPUsage(
apiDoc.NS_NS, 'Create a new namespace. Intermediate '
"namespaces are created automatically if they don't already "
'exist.')
topLevel.addUsage(usage)
usage.resourceClass = NamespacesResource
usage.successCode = http.CREATED
usage.addNote(
Note("""The new namespace will have permissions set
according to the user's defaults. There is no permission inheritance
in Fluidinfo."""))
usage.addReturn(
Return(apiDoc.PRECONDITION_FAILED, 'If the namespace already exists.'))
usage.addReturn(
Return(
apiDoc.NOT_FOUND,
"If a parent namespace does not exist and you do not have permission to "
'create it.'))
usage.addReturn(
Return(
apiDoc.UNAUTHORIZED, 'If the requesting user does not have ' +
apiDoc.CREATE + ' permission on the parent namespace.'))
usage.addReturn(
Return(
apiDoc.BAD_REQUEST,
def addBadRequestPayload(usage):
usage.addReturn(Return(BAD_REQUEST,
'''An error with the request payload. <a
href="http://doc.fluidinfo.com/fluidDB/api/'''
'''http.html#bad-request">More details</a>.'''))
def addNonExistentUser(usage):
usage.addReturn(
Return(PRECONDITION_FAILED,
"The user named in the URI does not exist."))
def addNeedBeUserOrAdmin(usage, perm):
usage.addReturn(
Return(UNAUTHORIZED,
"If the requesting user is not the user in the URI "
"and does not have " + perm + """ permission on the
relevant system tag."""))
def addUnknownExceptionUser(usage):
usage.addReturn(
Return(PRECONDITION_FAILED,
"The user named in the exceptions list does not exist."))
def addNeedTagPermOrAdmin(usage, perm):
usage.addReturn(
Return(UNAUTHORIZED,
"If the requesting user does not have " + perm +
" permission on the tag."))
def addMissingIntermediateNs(usage):
usage.addReturn(
Return(NOT_FOUND,
"If an intermediate namespace does not exist."))
Fluidinfo query language is described
<a href="http://doc.fluidinfo.com/fluidDB/queries.html">here</a>.''',
'string',
None,
mandatory=True))
usage.addArgument(
Argument(tagArg,
'''The name of a tag whose value should be returned. Repeat this
argument as many times as needed. All values are returned if '*' is
specified.''',
'string',
None,
mandatory=True))
usage.addReturn(Return(apiDoc.BAD_REQUEST, 'If no query or tag is given.'))
usage.addReturn(
Return(apiDoc.BAD_REQUEST, 'If the query string could not be parsed.'))
# TODO: fix the following description. How large is too large?
usage.addReturn(
Return(
apiDoc.REQUEST_ENTITY_TOO_LARGE,
"""If the query (or any of its sub-parts) results in too many
matching objects. The current limit is 1 million objects."""))
usage.addReturn(
Return(
apiDoc.UNAUTHORIZED,
'If the requesting user does not have ' + apiDoc.READ +
usage.addArgument(
Argument(actionArg,
"""The action whose permissions information is
sought. Possible values are: """ + possibleActions + '.',
'string',
mandatory=True))
apiDoc.addMissingIntermediateNs(usage)
apiDoc.addNoSuchNs(usage)
apiDoc.addNeedNsPermOrAdmin(usage, apiDoc.CONTROL)
usage.addReturn(
Return(apiDoc.BAD_REQUEST,
'If the %s argument is missing or invalid.' % actionArg))
apiDoc.addCannotRespondWithPayload(usage)
apiDoc.addOkOtherwise(usage)
responsePayload = JSONPayload()
responsePayload.addField(
PayloadField(
'policy', unicode, 'The policy (either %r or %r).' %
(permissions.OPEN, permissions.CLOSED)))
responsePayload.addField(
PayloadField('exceptions',
list,
'The names of the users who are exceptions to the policy.',
listType=unicode))