rock-n-code/discogs-service
1
0
Fork 0
Code Pull Requests Releases 8 Activity

User Identity endpoints (#11)

Browse Source 
This PR contains the work done to implement the *User Identity* endpoints of the **Discogs API** online service:
* GET `/users/{username}`
* POST `/users/{username}`
* GET `/users/{username}/contributions`
* GET `/users/{username}/submissions`

Reviewed-on: #11
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
This commit was merged in pull request #11.
This commit is contained in:
Javier Cicchelli
2025-10-15 21:59:32 +00:00
committed by Javier Cicchelli
parent 39e9dc5d53
commit 2c91cad0bf
1 changed files with 404 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/DiscogsService/openapi.yaml
+404 -15
View File
@@ -346,8 +346,8 @@ paths:
For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
operationId: getUserIdentity
security:
- Token: []
- KeySecret: []
- UserToken: []
- ConsumerKeySecret: []
- OAuth: []
responses:
'200':
@@ -477,8 +477,8 @@ paths:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
security:
- Token: []
- KeySecret: []
- UserToken: []
- ConsumerKeySecret: []
- OAuth: []
responses:
'200':
@@ -508,6 +508,9 @@ paths:
- $ref: '#/components/schemas/MasterResult'
- $ref: '#/components/schemas/ArtistResult'
- $ref: '#/components/schemas/LabelResult'
required:
- pagination
- results
'401':
$ref: '#/components/responses/Unauthorized'
'500':
@@ -576,6 +579,9 @@ paths:
type: array
items:
$ref: '#/components/schemas/ArtistRelease'
required:
- pagination
- releases
'404':
$ref: '#/components/responses/NotFound'
/labels/{label_id}:
@@ -640,6 +646,9 @@ paths:
type: array
items:
$ref: '#/components/schemas/LabelRelease'
required:
- pagination
- releases
'404':
$ref: '#/components/responses/NotFound'
/masters/{master_id}:
@@ -713,6 +722,9 @@ paths:
type: array
items:
$ref: '#/components/schemas/ReleaseVersion'
required:
- pagination
- versions
'404':
$ref: '#/components/responses/NotFound'
/releases/{release_id}:
@@ -806,8 +818,8 @@ paths:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/Rating'
security:
- Token: []
- KeySecret: []
- UserToken: []
- ConsumerKeySecret: []
- OAuth: []
responses:
'200':
@@ -842,8 +854,8 @@ paths:
- $ref: '#/components/parameters/ReleaseId'
- $ref: '#/components/parameters/Username'
security:
- Token: []
- KeySecret: []
- UserToken: []
- ConsumerKeySecret: []
- OAuth: []
responses:
'200':
@@ -896,6 +908,158 @@ paths:
- is_offensive
'404':
$ref: '#/components/responses/NotFound'
/users/{username}:
get:
tags:
- User Identity
summary: Get information about a user.
description: |
Retrieves a user profile by username.
In case of being authenticated as the requested user, the `email` property will be visible, and the `num_list` count will also include a user's private lists.
In case of being authenticated as the requested user, or a user's collection or wantlist is public, the `num_collection` and the `num_wantlist` properties will also be visible.
operationId: getUserProfile
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Successfully retrieved profile user information by a given username.
headers:
X-Discogs-RateLimit:
$ref: '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used:
$ref: '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
post:
tags:
- User Identity
summary: Update information about a user.
description: |
Edits some user profile information by username.
This endpoint requires authentication.
operationId: postUserProfile
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/Name'
- $ref: '#/components/parameters/HomePage'
- $ref: '#/components/parameters/Location'
- $ref: '#/components/parameters/Profile'
- $ref: '#/components/parameters/Currency'
security:
- UserToken: []
- ConsumerKeySecret: []
- OAuth: []
responses:
'200':
description: Successfully retrieved an updated profile user information by a given username.
headers:
X-Discogs-RateLimit:
$ref: '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used:
$ref: '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
'403':
$ref: '#/components/responses/NotAccessable'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/users/{username}/contributions:
get:
tags:
- User Identity
summary: Get contributions of a user.
description: |
Retrieves all the contributions or additions to releases, labels, and artist done by username.
This endpoints accepts pagination headers.
operationId: getUserContributions
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/SortField'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: Successfully retrieved items contributed by a user.
headers:
X-Discogs-RateLimit:
$ref: '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used:
$ref: '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
submissions:
description: A type that represents all items submitted by a user.
$ref: '#/components/schemas/UserItems'
required:
- pagination
- contributions
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/users/{username}/submissions:
get:
tags:
- User Identity
summary: Get submissions of a user.
description: |
Retrieves all the submissions or edits to releases, labels, and artist done by username.
This endpoints accepts pagination headers.
operationId: getUserSubmissions
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Successfully retrieved items submitted by a user.
headers:
X-Discogs-RateLimit:
$ref: '#/components/headers/RateLimit'
X-Discogs-RateLimit-Used:
$ref: '#/components/headers/RateLimitUsed'
X-Discogs-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
submissions:
description: A type that represents all items edited by a user.
$ref: '#/components/schemas/UserItems'
required:
- pagination
- submissions
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
components:
headers:
Link:
@@ -1002,6 +1166,14 @@ components:
in: query
schema:
type: string
HomePage:
description: A URI to a website of a user.
name: home_page
in: query
schema:
type: string
format: uri
example: https://www.some-home.page
Label:
description: A filter by label.
name: label
@@ -1016,6 +1188,13 @@ components:
schema:
type: integer
example: 1
Location:
description: A geographical location of a user.
name: location
in: query
schema:
type: string
example: Planet Earth
MasterId:
description: An identifier of a master.
name: master_id
@@ -1037,6 +1216,13 @@ components:
- label
- catno
- country
Name:
description: A real name of a user.
name: name
in: query
schema:
type: string
example: Some real name
Page:
description: A number of page of results to return.
name: page
@@ -1054,6 +1240,13 @@ components:
type: integer
minimum: 1
maximum: 100
Profile:
description: A biographical information about a user.
name: profile
in: query
schema:
type: string
example: Some biographical information about a user goes here...
Rating:
description: A number (between 1 and 5) for a rating of a release.
name: rating
@@ -1077,11 +1270,25 @@ components:
in: query
schema:
type: string
SortField:
description: A filter by field.
name: sort
in: query
schema:
type: string
enum:
- label
- artist
- title
- catno
- format
- rating
- year
- added
SortOrder:
description: The order to sort the results.
name: sort_order
in: query
required: false
schema:
type: string
enum:
@@ -1116,6 +1323,14 @@ components:
Malformed:
value:
message: An internal server error occurred. (Malformed query?)
NotAccessable:
description: A requested resource cannot be accessed due to a lack of permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
example:
message: You must have permission to access this resource.
NotFound:
description: A requested resource cannot be found.
content:
@@ -1125,7 +1340,7 @@ components:
example:
message: Resource not found.
Unauthorized:
description: A requested resource cannot be accessed.
description: A requested resource cannot be accessed due to a lack of authentication.
content:
application/json:
schema:
@@ -1754,9 +1969,7 @@ components:
- status
- styles
- title
- tracklist
- uri
- videos
ReleaseFormat:
description: A type that represents a format of a release.
type: object
@@ -2073,7 +2286,6 @@ components:
type: string
format: uri
required:
- id
- resource_url
- username
UserIdentity:
@@ -2085,6 +2297,183 @@ components:
consumer_name:
description: A name of an application a user utilizes to interacts with the service.
type: string
UserItems:
description: A type that represents all items added and/or edited by a user.
type: object
properties:
artists:
description: A list of artists added and/or edited by a user.
type: array
items:
$ref: '#/components/schemas/Artist'
labels:
description: A list of labels added and/or edited by a user.
type: array
items:
$ref: '#/components/schemas/Label'
releases:
description: A list of releases added and/or edited by a user.
type: array
items:
$ref: '#/components/schemas/Release'
UserProfile:
description: A type that represents a user profile.
allOf:
- $ref: '#/components/schemas/UserId'
- type: object
properties:
name:
description: A real name of a user.
type: string
email:
description: An e-mail address of a user, if any.
type: string
format: email
profile:
description: A biographical information of a user.
type: string
location:
description: A geographical location of a user.
type: string
uri:
description: A URL to the resource of a user.
type: string
format: uri
home_page:
description: A URI to a website of a user.
type: string
format: uri
registered:
description: A date and time a user registered to the service.
type: string
format: date-time
rank:
description: A number of rank of a user.
type: integer
curr_abbr:
description: A code of a currency used by a user in the marketplace.
type: string
minLength: 3
maxLength: 3
activated:
description: A flag that indicates whether a user is active or not.
type: boolean
marketplace_suspended:
description: A flag that indicates whether a user is suspended at the marketplace or not.
type: boolean
is_staff:
description: A flag that indicates whether a user is member of the staff at the service or not.
type: boolean
num_collection:
description: A number of items a user have in its collection.
type: integer
num_lists:
description: A number of list a user created.
type: integer
num_pending:
description: A number of items a user have in its pending list.
type: integer
num_for_sale:
description: A number of item a user have for sale in the marketplace.
type: integer
num_wantlist:
description: A number of items a user have in its want list, if any.
type: integer
rating_avg:
description: An average rating to the total of releases a user rated.
type: number
format: float
minimum: 0
maximum: 5
releases_contributed:
description: A number of releases that a user contributed information.
type: integer
releases_rated:
description: A number of release that a user rated.
type: integer
buyer_rating:
description: An average rating a user have in the marketplace as a buyer.
type: number
format: float
minimum: 0
maximum: 100
buyer_rating_stars:
description: A number of star rating a user have in the marketplace as a buyer.
type: integer
minimum: 0
maximum: 5
buyer_num_ratings:
description: A total number of ratings a user have in the marketplace as a buyer.
type: integer
seller_rating:
description: An average rating a user have in the marketplace as a seller.
type: number
format: float
minimum: 0
maximum: 100
seller_rating_stars:
description: A number of star rating a user have in the marketplace as a seller.
type: integer
minimum: 0
maximum: 5
seller_num_ratings:
description: A total number of ratings a user have in the marketplace as a seller.
type: integer
avatar_url:
description: A URL to the avatar of a user.
type: string
format: uri
banner_url:
description: A URL to th banner of a user.
type: string
format: uri
collection_fields_url:
description: A URL to the collection fields of a user.
type: string
format: uri
collection_folders_url:
description: A URL to the collection forlder of a user.
type: string
format: uri
inventory_url:
description: A URL to the inventory of a user.
type: string
format: uri
wantlist_url:
description: A URI to the want list of a user.
type: string
format: uri
required:
- activated
- avatar_url
- banner_url
- buyer_num_ratings
- buyer_rating
- buyer_rating_stars
- collection_fields_url
- collection_folders_url
- curr_abbr
- home_page
- inventory_url
- is_staff
- location
- marketplace_suspended
- name
- num_collection
- num_lists
- num_for_sale
- num_pending
- profile
- rating_avg
- rank
- registered
- releases_contributed
- releases_rated
- seller_num_ratings
- seller_rating
- seller_rating_stars
- uri
- wantlist_url
Video:
description: A type that represents a video.
type: object
@@ -2113,7 +2502,7 @@ components:
- title
- uri
securitySchemes:
KeySecret:
ConsumerKeySecret:
description: |
Discogs authentication using a key/secret pair.
@@ -2133,7 +2522,7 @@ components:
The `Authorization` header should be constructed according to OAuth 1.0a specs, for example: `OAuth oauth_consumer_key="...", oauth_nonce="...", ...`
type: http
scheme: oauth
Token:
UserToken:
description: |
Discogs authentication using a personal access token.