Update projects-v2.yaml

Author: Olaf Joppe

static/openapi-spec/projects-v2.yaml

@@ -7,6 +7,7 @@ info:
   contact:
     name: Mendix Support
     url: 'https://support.mendix.com'
+    email: support@mendix.com
 servers:
   - url: 'https://projects-api.home.mendix.com/v2'
 paths:
@@ -104,28 +105,28 @@ paths:
               properties:
                 categories:
                   type: array
-                  description: 'Array of category assignments. Each item identifies a company custom field (fieldId) and the Code/Value to assign. Used when updating `category`.'
+                  description: 'Array of category assignments. Each item identifies a company category (categoryId) and the Code/Value to assign. Used when updating `category`.'
                   items:
                     type: object
                     required:
-                      - fieldId
+                      - categoryId
                       - value
                     properties:
-                      fieldId:
+                      categoryId:
                         type: string
-                        description: 'Identifier of the company custom field'
+                        description: 'Identifier of the company category'
                         maxLength: 36
                       value:
                         type: string
-                        description: 'The Code or Value to assign to the custom field. An empty string clears the assignment.'
+                        description: 'The Code or Value to assign to the category. An empty string clears the assignment.'
                         maxLength: 500
             examples:
               category-update:
                 value:
                   categories:
-                    - fieldId: '123456789'
+                    - categoryId: '123456789'
                       value: 'NLD'
-                    - fieldId: '987654321'
+                    - categoryId: '987654321'
                       value: ''
       responses:
         '204':
@@ -263,7 +264,7 @@ paths:
       tags:
         - Projects
       summary: 'Get the status of a job creating a project'
-      description: 'Returns the status of the process that creates a project.</br>Every request must be authenticated through a Personal Access Token containing the `mx:app:create` scope.'
+      description: 'Returns the status of the process that creates a project.</br>Every request must be authenticated by a Personal Access Token containing the scope `mx:app:create`.'
       operationId: get-project-job
       parameters:
         - $ref: '#/components/parameters/job-id'
@@ -281,13 +282,13 @@ paths:
       tags:
         - Users
       summary: 'Get a list of projects the user is a team member of'
-      description: 'Returns a list of projects that the specified user is a team member of. The output is restricted based on the authorization of the calling user. Mendix administrators will get a list of all projects (active or inactive) owned by their company for the specified user. This includes external users hired by them to work on their projects. Project members must be active and will get a list of all active projects that they themselves are a team member of. Project members cannot request a list of projects on behalf of someone else.<br/>The result is sorted alphabetically by project name in ascending order.</br>Every request must be authenticated through a Personal Access Token containing the `mx:app:metadata:read` scope.'
+      description: 'Returns a list of projects that the specified user is a team member of. The output is restricted based on the authorization of the calling user. Mendix administrators will get a list of all projects (active or inactive) owned by their company for the specified user. This includes external users hired by them to work on their projects. Project members must be active and will get a list of all active projects that they themselves are a team member of. Project members cannot request a list of projects on behalf of someone else.<br/>The result is sorted alphabetically by project name in ascending order.</br>Every request must be authenticated by a Personal Access Token containing the scope `mx:app:metadata:read`.'
       operationId: get-user-projects
       parameters:
         - $ref: '#/components/parameters/user-id'
         - name: permissions
           in: query
-          description: 'A comma-separated list of permissions that the user has within the project. Possible values are `administrator`, `technicalcontact`, `repositoryaccess`, `cloudaccess`, `storyaccess`, `invitationrights`. The values are applied to the query using the AND operator.'
+          description: 'A comma separated list of permissions the user has within the project. Possible values are `administrator`, `technicalcontact`, `repositoryaccess`, `cloudaccess`, `storyaccess`, `invitationrights`. The values are applied to the query using the AND operator'
           schema:
             type: string
         - name: isPinnedByUser
@@ -311,13 +312,13 @@ paths:
       tags:
         - Accounts
       summary: 'Get a list of project roles for a specified account.'
-      description: 'Returns a list of project roles for a specified account or company. The output is restricted based on the authorization of the calling user. The calling user must be a member of the specified company.</br></br>Every request must be authenticated through a Personal Access Token containing the `mx:app:roles:read` scope.'
+      description: 'Returns a list of project roles for a specified account (or company). The output is restricted based on the authorization of the calling user. The calling user must be a member of the specified company.</br></br>Every request must be authenticated by a Personal Access Token containing the scope `mx:app:roles:read`.'
       operationId: get-company-roles
       parameters: 
         - $ref: '#/components/parameters/account-id'
         - name: changedSince
           in: query
-          description: 'If supplied, only roles created or changed since this date will be returned. The date and time should be provided in the ISO 8601 format, for example `2024-08-21T11:07:00Z`.'
+          description: 'If supplied only roles created or changed since this date will be returned. This date time should be provided in the ISO 8601 format, for example `2024-08-21T11:07:00Z`'
           schema:
             type: string
             format: date-time
@@ -339,12 +340,12 @@ paths:
       tags:
         - Accounts
       summary: 'Get a list of company-owned projects'
-      description: 'Returns a list of projects owned by the company of the requesting user. Inactive projects are only returned if the requesting user is a Mendix Admin.</br>Every request must be authenticated through a Personal Access Token containing the `mx:app:metadata:read` scope.'
+      description: 'Returns a list of projects owned by the company of the requesting user. Inactive projects are only returned if the requesting user is a Mendix Administrator.</br>Every request must be authenticated by a Personal Access Token containing the scope `mx:app:metadata:read`.'
       operationId: get-account-projects
       parameters:
         - name: createdSince
           in: query
-          description: 'Retrieve all projects created after this date. Time is in UTC and must be provided in this format: 2020-01-16T05:53:28Z.'
+          description: 'Retrieve all projects created after this date. Time is in UTC and must be provided in this format: 2020-01-16T05:53:28Z'
           schema:
             type: string
         - $ref: '#components/parameters/limit'
@@ -394,7 +395,7 @@ components:
       description: Unique identifier in the Mendix Platform.
     Account:
       type: object
-      description: 'Account or company that owns the resource'
+      description: 'Account (or company) that owns the resource'
       properties:
         accountId: 
           type: string
@@ -420,7 +421,7 @@ components:
           $ref: '#/components/schemas/Account'
     Page:
       type: object
-      description: 'Contains information about the current page, and the total number of elements to be retrieved.'
+      description: 'Contains information about the current page, and total elements to be retrieved'
       properties:
         totalElements:
           type: integer
@@ -452,7 +453,7 @@ components:
           description: 'URL of the cloud portal the project is hosted on.'
         active:
           type: boolean
-          description: 'Indicates whether a project is active and can be maintained by a team. Inactive projects will only be returned to Mendix Admins. Note this attribute does not indicate whether the project is actively deployed or running in the cloud.'
+          description: 'Indicates whether a project is active and can be maintained by a team. Inactive projects will only be returned to Mendix administrators. Note this attribute does not indicate whether the project is actively deployed or running in the cloud.'
         account:
           $ref: "#/components/schemas/Account"
     ProjectRole:
@@ -498,13 +499,13 @@ components:
             properties:
               environmentType:
                 type: string
-                description: 'The type of environment.'
+                description: 'Type of the environment.'
                 enum:
                 - non_production
                 - production
               accessType:
                 type: string
-                description: 'The type of access.'
+                description: 'Type of the access.'
                 enum:
                 - no_access
                 - access
@@ -517,7 +518,7 @@ components:
                 description: 'Indicates whether the role has environment transportation rights.'
               hasBackupAccess:
                 type: boolean
-                description: 'Indicates whether the role is allowed to access the environment''s backups.'
+                description: 'Indicates whether the role is allowed to access the environment'' backups.'
               hasMonitoringAccess:
                 type: boolean
                 description: 'Indicates whether the role has access to the environment''s monitoring.'
@@ -590,7 +591,7 @@ components:
                 description: Unique identifier of the member
               roleId:
                 type: string
-                description: The unique identifier of the role that will be assigned to the member.
+                description: Unique identifier of the role that will be assigned to the member
             x-examples:
               Example 1:
                 memberId: d207ff9b-3603-4060-aa0a-62d5b264bac7
@@ -608,7 +609,7 @@ components:
             properties:
               name:
                 type: string
-                description: The name of the project.
+                description: Name of the project
                 maxLength: 100
               summary:
                 type: string
@@ -617,10 +618,10 @@ components:
                 maxLength: 400
               image:
                 type: string
-                description: 'Base-64 encoded string of the project icon image. The file size is limited to 5MB, minimum of 200 x 200 px and maximum of 400 x 400 px.'
+                description: 'Base-64 encoded string of the project icon image. The file size is limited to 5MB, minimum of 200 x 200 px and amaximum of 400 x 400 px.'
               templateId:
                 type: string
-                description: 'Identifier of the template that the project will be copied from. If empty, the default template is used.'
+                description: 'Identifier of the template that the project will be copied from. If empty, the default template will be used.'
                 format: uuid
                 pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
                 maxLength: 36
@@ -642,7 +643,7 @@ components:
   securitySchemes:
     PersonalAccessToken:
       type: apiKey
-      description: "For more information about requesting and using a token, refer to the [documentation](https://docs.mendix.com/community-tools/mendix-profile/user-settings/#pat).<br/>The header must be set to `MxToken <Your PAT>`."
+      description: "For more information about requesting and using a token see the [documentation](https://docs.mendix.com/community-tools/mendix-profile/user-settings/#pat).<br/>The header must be set to `MxToken <Your PAT>`."
       name: Authorization
       in: header
   responses:
@@ -678,7 +679,7 @@ components:
                       description: Date and time in UTC when the project was created.
                     active:
                       type: boolean
-                      description: 'Indicates whether a project is active or not. Inactive projects will only be returned to Mendix Admins.'
+                      description: 'Indicates whether a project is active or not. Inactive projects will only be returned to Mendix administrators.'
                     createdBy:
                       type: object
                       description: Contains information about the person that created this project.
@@ -743,10 +744,10 @@ components:
                 description: URL of the project image/logo.
               createdOn:
                 type: string
-                description: Date and time when the project was created, expressed in UTC.
+                description: Date and time in UTC when the project was created.
               active:
                 type: boolean
-                description: Indicates whether a project is active or not. Inactive projects will only be returned to Mendix Admins.
+                description: Indicates whether a project is active or not. Inactive projects will only be returned to Mendix administrators.
               createdBy:
                 type: object
                 description: Contains information about the person that created this project.
@@ -764,7 +765,7 @@ components:
                 maxLength: 50
               storyTool:
                 type: string
-                description: The tool or service used to manage the workload of the project. Can be empty if no tool has been chosen yet.
+                description: The tool or service used to manage the workload of the project. Could be empty if no tool has been chosen yet
                 enum:
                 - Epics
                 - Jira
@@ -781,10 +782,10 @@ components:
                 - Mendix_for_Private_Cloud
               targetCloud: 
                 type: string
-                description: URL of the cloud portal where the project is hosted
+                description: URL of the cloud portal the project is hosted on
               members:
                 type: array
-                description: Array of members in the project. Inactive members will only be returned to Mendix Admins.
+                description: Array of members in the project. Inactive members will only be returned for Mendix Administrators
                 items:
                   allOf:
                     - $ref: '#/components/schemas/User'
@@ -819,7 +820,7 @@ components:
                       maxLength: 500
                     categoryId:
                       type: string
-                      description: ID of the category (also known as 'FieldId')
+                      description: ID of the category (also known as categoryId)
                       maxLength: 36
                     values:
                       type: array
@@ -915,7 +916,7 @@ components:
                       description: URL of the avatar image of the member.
                     isActive:
                       type: boolean
-                      description: Indicates whether the member is an active member on the platform.
+                      description: Indicator of whether the member is an active member on the platform
                     company:
                       type: object
                       description: Contains information of the company to which the member belongs.
@@ -959,7 +960,7 @@ components:
             properties:
               jobId:
                 type: string
-                description: Unique identifier of the job that created the project. Use this ID to query the status of the process.
+                description: Unique identifier of the job that creates the project. Use this ID to query the status of the process.
                 format: uuid
                 pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
                 minLength: 36
@@ -987,7 +988,7 @@ components:
                 description: Error message provided in case the job has failed
               projectId:
                 type: string
-                description: Identifier of the newly created project
+                description: Identifier of the new created project
                 format: uuid
                 pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
                 maxLength: 36
@@ -1039,7 +1040,7 @@ components:
                           description: 'Indicates whether the user is allowed to make changes to the project''s model.'
                         hasCloudAccess:
                           type: boolean
-                          description: 'Indicates whether the user has access to cloud environments.'
+                          description: 'Indicates whether the user has access to the cloud environments.'
                         hasStoryAccess:
                           type: boolean
                           description: 'Indicates whether the user has access to Stories and Feedback of the project.'