@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api FinSpace Public API
@version 2020-07-13
@auth AWS SigV4
@endpoints 31
@hint download_for_search
@toc permission-group(8), datasets(8), datasetsv2(5), user(8), credentials(1), workingLocationV1(1)

@group permission-group
@endpoint POST /permission-group/{permissionGroupId}/users/{userId}
@desc Adds a user to a permission group to grant permissions for actions a user can perform in FinSpace.
@required {permissionGroupId: str, userId: str}
@optional {clientToken: str}
@returns(200) {statusCode: int?}

@endgroup

@group datasets
@endpoint POST /datasets/{datasetId}/changesetsv2
@desc Creates a new Changeset in a FinSpace Dataset.
@required {datasetId: str, changeType: str, sourceParams: map<str,str>, formatParams: map<str,str>}
@optional {clientToken: str}
@returns(200) {datasetId: str?, changesetId: str?}

@endpoint POST /datasets/{datasetId}/dataviewsv2
@desc Creates a Dataview for a Dataset.
@required {datasetId: str, destinationTypeParams: DataViewDestinationTypeParams}
@optional {clientToken: str, autoUpdate: bool, sortColumns: [str], partitionColumns: [str], asOfTimestamp: int(i64)}
@returns(200) {datasetId: str?, dataViewId: str?}

@endgroup

@group datasetsv2
@endpoint POST /datasetsv2
@desc Creates a new FinSpace Dataset.
@required {datasetTitle: str, kind: str, permissionGroupParams: PermissionGroupParams}
@optional {clientToken: str, datasetDescription: str, ownerInfo: DatasetOwnerInfo, alias: str, schemaDefinition: SchemaUnion}
@returns(200) {datasetId: str?}

@endgroup

@group permission-group
@endpoint POST /permission-group
@desc Creates a group of permissions for various actions that a user can perform in FinSpace.
@required {name: str, applicationPermissions: [str]}
@optional {description: str, clientToken: str}
@returns(200) {permissionGroupId: str?}

@endgroup

@group user
@endpoint POST /user
@desc Creates a new user in FinSpace.
@required {emailAddress: str, type: str}
@optional {firstName: str, lastName: str, apiAccess: str, apiAccessPrincipalArn: str, clientToken: str}
@returns(200) {userId: str?}

@endgroup

@group datasetsv2
@endpoint DELETE /datasetsv2/{datasetId}
@desc Deletes a FinSpace Dataset.
@required {datasetId: str}
@optional {clientToken: str}
@returns(200) {datasetId: str?}

@endgroup

@group permission-group
@endpoint DELETE /permission-group/{permissionGroupId}
@desc Deletes a permission group. This action is irreversible.
@required {permissionGroupId: str}
@optional {clientToken: str}
@returns(200) {permissionGroupId: str?}

@endgroup

@group user
@endpoint POST /user/{userId}/disable
@desc Denies access to the FinSpace web application and API for the specified user.
@required {userId: str}
@optional {clientToken: str}
@returns(200) {userId: str?}

@endgroup

@group permission-group
@endpoint DELETE /permission-group/{permissionGroupId}/users/{userId}
@desc Removes a user from a permission group.
@required {permissionGroupId: str, userId: str}
@optional {clientToken: str}
@returns(200) {statusCode: int?}

@endgroup

@group user
@endpoint POST /user/{userId}/enable
@desc Allows the specified user to access the FinSpace web application and API.
@required {userId: str}
@optional {clientToken: str}
@returns(200) {userId: str?}

@endgroup

@group datasets
@endpoint GET /datasets/{datasetId}/changesetsv2/{changesetId}
@desc Get information about a Changeset.
@required {datasetId: str, changesetId: str}
@returns(200) {changesetId: str?, changesetArn: str?, datasetId: str?, changeType: str?, sourceParams: map<str,str>?, formatParams: map<str,str>?, createTime: int(i64)?, status: str?, errorInfo: ChangesetErrorInfo?{errorMessage: str?, errorCategory: str?}, activeUntilTimestamp: int(i64)?, activeFromTimestamp: int(i64)?, updatesChangesetId: str?, updatedByChangesetId: str?}

@endpoint GET /datasets/{datasetId}/dataviewsv2/{dataviewId}
@desc Gets information about a Dataview.
@required {dataViewId: str, datasetId: str}
@returns(200) {autoUpdate: bool?, partitionColumns: [str]?, datasetId: str?, asOfTimestamp: int(i64)?, errorInfo: DataViewErrorInfo?{errorMessage: str?, errorCategory: str?}, lastModifiedTime: int(i64)?, createTime: int(i64)?, sortColumns: [str]?, dataViewId: str?, dataViewArn: str?, destinationTypeParams: DataViewDestinationTypeParams?{destinationType: str, s3DestinationExportFileFormat: str?, s3DestinationExportFileFormatOptions: map<str,str>?}, status: str?}

@endgroup

@group datasetsv2
@endpoint GET /datasetsv2/{datasetId}
@desc Returns information about a Dataset.
@required {datasetId: str}
@returns(200) {datasetId: str?, datasetArn: str?, datasetTitle: str?, kind: str?, datasetDescription: str?, createTime: int(i64)?, lastModifiedTime: int(i64)?, schemaDefinition: SchemaUnion?{tabularSchemaConfig: SchemaDefinition?{columns: [ColumnDefinition]?, primaryKeyColumns: [str]?}}, alias: str?, status: str?}

@endgroup

@group datasets
@endpoint POST /datasets/{datasetId}/dataviewsv2/{dataviewId}/external-access-details
@desc Returns the credentials to access the external Dataview from an S3 location. To call this API:   You must retrieve the programmatic credentials.   You must be a member of a FinSpace user group, where the dataset that you want to access has Read Dataset Data permissions.
@required {dataViewId: str, datasetId: str}
@returns(200) {credentials: AwsCredentials?{accessKeyId: str?, secretAccessKey: str?, sessionToken: str?, expiration: int(i64)?}, s3Location: S3Location?{bucket: str, key: str}}

@endgroup

@group permission-group
@endpoint GET /permission-group/{permissionGroupId}
@desc Retrieves the details of a specific permission group.
@required {permissionGroupId: str}
@returns(200) {permissionGroup: PermissionGroup?{permissionGroupId: str?, name: str?, description: str?, applicationPermissions: [str]?, createTime: int(i64)?, lastModifiedTime: int(i64)?, membershipStatus: str?}}

@endgroup

@group credentials
@endpoint GET /credentials/programmatic
@desc Request programmatic credentials to use with FinSpace SDK. For more information, see Step 2. Access credentials programmatically using IAM access key id and secret access key.
@required {environmentId: str}
@optional {durationInMinutes: int(i64)}
@returns(200) {credentials: Credentials?{accessKeyId: str?, secretAccessKey: str?, sessionToken: str?}, durationInMinutes: int(i64)?}

@endgroup

@group user
@endpoint GET /user/{userId}
@desc Retrieves details for a specific user.
@required {userId: str}
@returns(200) {userId: str?, status: str?, firstName: str?, lastName: str?, emailAddress: str?, type: str?, apiAccess: str?, apiAccessPrincipalArn: str?, createTime: int(i64)?, lastEnabledTime: int(i64)?, lastDisabledTime: int(i64)?, lastModifiedTime: int(i64)?, lastLoginTime: int(i64)?}

@endgroup

@group workingLocationV1
@endpoint POST /workingLocationV1
@desc A temporary Amazon S3 location, where you can copy your files from a source location to stage or use as a scratch space in FinSpace notebook.
@optional {locationType: str}
@returns(200) {s3Uri: str?, s3Path: str?, s3Bucket: str?}

@endgroup

@group datasets
@endpoint GET /datasets/{datasetId}/changesetsv2
@desc Lists the FinSpace Changesets for a Dataset.
@required {datasetId: str}
@optional {maxResults: int, nextToken: str}
@returns(200) {changesets: [ChangesetSummary]?, nextToken: str?}

@endpoint GET /datasets/{datasetId}/dataviewsv2
@desc Lists all available Dataviews for a Dataset.
@required {datasetId: str}
@optional {nextToken: str, maxResults: int}
@returns(200) {nextToken: str?, dataViews: [DataViewSummary]?}

@endgroup

@group datasetsv2
@endpoint GET /datasetsv2
@desc Lists all of the active Datasets that a user has access to.
@optional {nextToken: str, maxResults: int}
@returns(200) {datasets: [Dataset]?, nextToken: str?}

@endgroup

@group permission-group
@endpoint GET /permission-group
@desc Lists all available permission groups in FinSpace.
@required {maxResults: int}
@optional {nextToken: str}
@returns(200) {permissionGroups: [PermissionGroup]?, nextToken: str?}

@endgroup

@group user
@endpoint GET /user/{userId}/permission-groups
@desc Lists all the permission groups that are associated with a specific user.
@required {userId: str, maxResults: int}
@optional {nextToken: str}
@returns(200) {permissionGroups: [PermissionGroupByUser]?, nextToken: str?}

@endpoint GET /user
@desc Lists all available users in FinSpace.
@required {maxResults: int}
@optional {nextToken: str}
@returns(200) {users: [User]?, nextToken: str?}

@endgroup

@group permission-group
@endpoint GET /permission-group/{permissionGroupId}/users
@desc Lists details of all the users in a specific permission group.
@required {permissionGroupId: str, maxResults: int}
@optional {nextToken: str}
@returns(200) {users: [UserByPermissionGroup]?, nextToken: str?}

@endgroup

@group user
@endpoint POST /user/{userId}/password
@desc Resets the password for a specified user ID and generates a temporary one. Only a superuser can reset password for other users. Resetting the password immediately invalidates the previous password associated with the user.
@required {userId: str}
@optional {clientToken: str}
@returns(200) {userId: str?, temporaryPassword: str?}

@endgroup

@group datasets
@endpoint PUT /datasets/{datasetId}/changesetsv2/{changesetId}
@desc Updates a FinSpace Changeset.
@required {datasetId: str, changesetId: str, sourceParams: map<str,str>, formatParams: map<str,str>}
@optional {clientToken: str}
@returns(200) {changesetId: str?, datasetId: str?}

@endgroup

@group datasetsv2
@endpoint PUT /datasetsv2/{datasetId}
@desc Updates a FinSpace Dataset.
@required {datasetId: str, datasetTitle: str, kind: str}
@optional {clientToken: str, datasetDescription: str, alias: str, schemaDefinition: SchemaUnion}
@returns(200) {datasetId: str?}

@endgroup

@group permission-group
@endpoint PUT /permission-group/{permissionGroupId}
@desc Modifies the details of a permission group. You cannot modify a permissionGroupID.
@required {permissionGroupId: str}
@optional {name: str, description: str, applicationPermissions: [str], clientToken: str}
@returns(200) {permissionGroupId: str?}

@endgroup

@group user
@endpoint PUT /user/{userId}
@desc Modifies the details of the specified user. You cannot update the userId for a user.
@required {userId: str}
@optional {type: str, firstName: str, lastName: str, apiAccess: str, apiAccessPrincipalArn: str, clientToken: str}
@returns(200) {userId: str?}

@endgroup

@end