Child pages
  • SaveUser
Skip to end of metadata
Go to start of metadata

Description

The SaveUser API allows the Account Owner to create or update a User.

 What is a User?

With Apstrata, you can build multi-user applications. In order to be able to read or write data to an apstrata account store, you have to be the Account Owner or you have to be registered as a User in the apstrata account. API requests signed with a User password are User requests as opposed to owner requests which are signed with the account secret.

When you register with Apstrata, an account will be created for you. With each account creation, there is a default user Schema named "apsdb_user" that gets created. The purpose of this Schema is to give the owner the possibility of defining custom user profiles. Hence, an owner can add new fields, define permissions, and define validation rules for each field. When saving users, custom user attributes can be set and validated automatically based on the rules defined for each one. The fields already defined in the default user Schema are required and should not be removed. This user schema is not meant to be used for saving non-user documents.

A User entity is persisted as a Document in the apstrata account user directory Store, based on the Schema named "apsdb_user".

A User can belong to zero or more Groups defining his read and write permissions.

A user can be suspended by calling SaveUser and setting the system field "isSuspended" to true. A suspended user still exists in the system but is treated as if he was deleted. Any request made to Apstrata with this user will return an exception saying that the signature is invalid. The user can be reactivated by calling SaveUser and setting the field "isSuspended" back to false. By default, the ACL of this field are set in a way that only the owner of the account can suspend or un-suspend a user but you are free to change those ACLs by updating your user schema.

Note that owners will always have the permission to call the GetUser and SaveUser APIs, but Users can only read or update their own profile Documents. In other words, the permissions defined in the Schema ACLs can only be used to restrict Users from accessing their own profile Document or other Users profile Documents.

For more details about schema definition, please refer to Document Schema Definition.

All users have the default system fields "groups", "name", "login", "email", "password" and "isSuspended". The fields "name", "email", and "password" are single valued. Any other parameters passed to SaveUser will be treated as application-defined attributes and will be treated as multi-valued fields. Please note that except for these specific user fields, SaveUser behaves exactly like the SaveDocument API.

User management APIs may only be called using the account owner credentials from within server scripts, or by a user to access his own profile.

Specific Request Parameters

(Refer to Common Request Parameters)

Name

Description

Required

Default

Possible Values

login

The username used to authenticate a user’s requests.

Yes

 

Alphanumeric characters, "@" "_" "." and "-" Maximum length 243 characters

password

The user’s password that will be used to sign the user’s requests

Yes on first creation. No on update. Set empty if sent empty.

 

 

name

The full name of the user

Yes. Set empty if sent empty.

 

 

email

The email of the user

No. Set empty if sent empty.

 

 

groups

The multiple field of groups to which the user will be added.

No. If sent empty or if one group is invalid, the error "Invalid Group" will be thrown.

 

 

isSuspended

The field used to specify if a user is suspended or not. Note that a suspended user still exists in the system but is treated as if he was deleted. He can be reactivated by calling SaveUser with the field isSuspended=true. 

No.

 true

 true or false

apsdb.update

Sent in case the user wants to update existing user. Sent user should be valid.

No. If sent empty or false or not sent, user will be created. If sent equal to true and sent user exists and is valid, user is updated.

 

 

[fieldName]

This parameter name in the request is the name of the custom user attribute to be stored, and its value is the value of the attribute.

No. If field already exists and is sent empty, field will be deleted, else the new value will override the existing value. Note that it cannot be sent as multiple as an exception will be thrown.

 

 

[fieldName].apsdb.fieldType

The type of the data to be stored in the corresponding attribute field. The field is specified by the first portion of the parameter name. i.e. This parameter will set the content type of the field whose name is [fieldName].
Refer to the Creating Documents section under the SaveDocument page for more details about the field types.

No

string

string, numeric, date, text, file, geospatial.

[fieldName].apsdb.delete

Parameter used to delete a field or a specific value.

No

 

 

apsdb.multivalueAppend

Specifies that the given field values will be appended to, instead of replacing, the current field values. Contains a comma separated list of field names to which the values specified will be appended.

No

 

 

apsdb.runAs

Allows the owner to run a service as one of his own users. The possible values are any of the usernames.

No

 

 

apsdb.globalDateFormatSpecifies which date format to use for any date fields values that are passed to be saved for the user.No  

 

Specific Response Elements

(Refer to Common Response Elements)

Specific Logical Errors

(Refer to Common Logical Error Codes and SaveDocument API's "Specific Logical Errors" section)

Below is the list of additional errors you might get in the special case of saving a user document.

Error

Message

Status Code

PASSWORD_REQUIRED

The password was not sent in the request.

400

INVALID_EMAIL

An invalid email address is sent in the request.

400

DUPLICATE_USER

The user [login] already exists.

400

INVALID_GROUP

Trying to add a user [login] to a group [groupName] that does not exist.

400

PARAMETER_REQUIRED

The parameter [login] is required in SaveUser

400

INVALID_USER

The user [login] does not exist.

400

NAME_REQUIRED

The name was not sent in the request.

400

INVALID_FIELD_VALUE

failed to update user [login]

400

INVALID_FIELD_VALUE

failed to create user [login]

400

INVALID_FIELD_VALUE

Field [fieldName] cannot contain values that are not strings

400

INVALID_FIELD_VALUE

Field [fieldName] cannot contain values that are not numeric

400

INVALID_FIELD_VALUE

Field [fieldName] cannot contain values that are not dates

400

INVALID_FIELD_VALUE

Field [fieldName] cannot contain values that are not text

400

INVALID_FIELD_VALUE

Field [fieldName] has an invalid value

400

INVALID_USERNAME

 

400

INVALID_PARAMETER_VALUEThis is a reserved login. 

 

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/SaveUser?apsws.time=[timestamp]&apsws.authSig=[signature] 



POST parameters:

login = [user_login]
password = [user_password]
name = [user_full_name]
email = [user_email]
apsdb.update = [true|false]
groups = [user_group]


Sample XML Response

Success XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>success</status>        
		<statusCode>200</statusCode>
    </metadata>
</response>


Failure XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[failMsg]</errorDetail>
    </metadata>
</response>


Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "success"
	"statusCode": "200"
 }
}}
  • No labels