From 71c2fd717680a09c04447c595ed1d5c741b77b89 Mon Sep 17 00:00:00 2001 From: Emelia Smith Date: Wed, 15 May 2024 17:12:09 +0200 Subject: [PATCH 1/3] Improve deprecation messaging for Application#vapid_key --- content/en/entities/Application.md | 7 +++---- content/en/methods/apps.md | 9 +++++++-- content/en/methods/instance.md | 12 ++++++++---- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/content/en/entities/Application.md b/content/en/entities/Application.md index 5ce71c8e36..92cc61f76a 100644 --- a/content/en/entities/Application.md +++ b/content/en/entities/Application.md @@ -17,8 +17,7 @@ aliases: [ ```json { "name": "test app", - "website": null, - "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" + "website": null } ``` @@ -60,8 +59,8 @@ aliases: [ **Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "methods/apps#create" >}}). Equivalent to [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) and [Instance#vapid_public_key]({{< relref "entities/Instance#vapid_public_key" >}})\ **Type:** String\ **Version history:**\ -2.8.0 - added -4.3.0 - deprecated pending removal +2.8.0 - added\ +4.3.0 - deprecated pending removal, please see [api/v2/instance]({{< relref "methods/Instance#v2">}}) for this value (`configuration.vapid.public_key`) ## See also diff --git a/content/en/methods/apps.md b/content/en/methods/apps.md index d1dd5b2679..85409fd182 100644 --- a/content/en/methods/apps.md +++ b/content/en/methods/apps.md @@ -29,9 +29,11 @@ Create a new application to obtain OAuth2 credentials. **OAuth:** Public\ **Version history:**\ 0.0.0 - added\ -2.7.2 - now returns `vapid_key` +2.7.2 - now returns `vapid_key`\ +4.3.0 - deprecated `vapid_key`, please see [api/v2/instance]({{< relref "methods/Instance#v2">}}) #### Request + ##### Form data parameters client_name @@ -47,6 +49,7 @@ website : String. A URL to the homepage of your app #### Response + ##### 200: OK Store the `client_id` and `client_secret` in your cache, as these will be used to obtain OAuth tokens. @@ -87,7 +90,8 @@ Confirm that the app's OAuth2 credentials work. **OAuth level:** App token + `read`\ **Version history:**\ 2.0.0 - added\ -2.7.2 - now returns `vapid_key` +2.7.2 - now returns `vapid_key`\ +4.3.0 - deprecated `vapid_key`, please see [api/v2/instance]({{< relref "methods/Instance#v2">}}) #### Request @@ -97,6 +101,7 @@ Authorization : {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response + ##### 200: OK If the Authorization header was provided with a valid token, you should see your app returned as an Application entity. diff --git a/content/en/methods/instance.md b/content/en/methods/instance.md index ee78daa4dc..ca1606ef11 100644 --- a/content/en/methods/instance.md +++ b/content/en/methods/instance.md @@ -28,7 +28,8 @@ Obtain general information about the server. **Returns:** [Instance]({{< relref "entities/Instance" >}})\ **OAuth:** Public\ **Version history:**\ -4.0.0 - added +4.0.0 - added\ +4.3.0 - added `configuration.vapid.public_key` #### Response @@ -186,7 +187,6 @@ Obtain general information about the server. } ``` - --- ## List of connected domains {#peers} @@ -252,6 +252,7 @@ Authorization : Provide this header with `Bearer ` to gain authorized access to this API method. #### Response + ##### 200: OK Each hash in the array will contain the following attributes: @@ -359,7 +360,6 @@ If the instance is in whitelist mode and the Authorization header is missing or ## List of rules {#rules} - ```http GET /api/v1/instance/rules HTTP/1.1 ``` @@ -372,6 +372,7 @@ Rules that the users of this service should follow. 3.4.0 - added #### Response + ##### 200: OK ```json @@ -426,6 +427,7 @@ Authorization : Provide this header with `Bearer ` to gain authorized access to this API method. #### Response + ##### 200: OK The complete list of domains blocked by this instance @@ -481,6 +483,7 @@ Obtain an extended description of this server 4.0.0 - added #### Response + ##### 200: OK ```json @@ -506,6 +509,7 @@ Translation language pairs supported by the translation engine used by the serve 4.2.0 - added #### Response + ##### 200: OK All source and target language pairs supported by the server. @@ -528,7 +532,7 @@ In the following sample response showing support for translating a status writte GET /api/v1/instance HTTP/1.1 ``` -Obtain general information about the server. +Obtain general information about the server. See [api/v2/instance]({{< relref "methods/Instance#v2">}}) instead. **Returns:** [V1::Instance]({{< relref "entities/V1_Instance" >}})\ **OAuth:** Public\ From 1f45985ce5f4f05ce1cca815d3e9e1ccfa0f6f0f Mon Sep 17 00:00:00 2001 From: Emelia Smith Date: Wed, 15 May 2024 17:13:19 +0200 Subject: [PATCH 2/3] Format JSON examples in Instance methods --- content/en/methods/instance.md | 175 ++++++++++++++++----------------- 1 file changed, 85 insertions(+), 90 deletions(-) diff --git a/content/en/methods/instance.md b/content/en/methods/instance.md index ca1606ef11..de86ae8bd6 100644 --- a/content/en/methods/instance.md +++ b/content/en/methods/instance.md @@ -55,9 +55,7 @@ Obtain general information about the server. "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png" } }, - "languages": [ - "en" - ], + "languages": ["en"], "configuration": { "urls": { "streaming": "wss://mastodon.social" @@ -435,17 +433,17 @@ The complete list of domains blocked by this instance ```json [ { - "domain":"birb.elfenban.de", - "digest":"5d2c6e02a0cced8fb05f32626437e3d23096480b47efbba659b6d9e80c85d280", - "severity":"suspend", - "comment":"Third-party bots" + "domain": "birb.elfenban.de", + "digest": "5d2c6e02a0cced8fb05f32626437e3d23096480b47efbba659b6d9e80c85d280", + "severity": "suspend", + "comment": "Third-party bots" }, { - "domain":"birdbots.leptonics.com", - "digest":"ce019d8d32cce8e369ac4367f4dc232103e6f489fbdd247fb99f9c8a646078a4", - "severity":"suspend", - "comment":"Third-party bots" - }, + "domain": "birdbots.leptonics.com", + "digest": "ce019d8d32cce8e369ac4367f4dc232103e6f489fbdd247fb99f9c8a646078a4", + "severity": "suspend", + "comment": "Third-party bots" + } // ... ] ``` @@ -465,6 +463,7 @@ Invalid or missing Authorization header, if the admin has chosen to show domain The admin has chosen to show domain blocks to no one. The response body is empty; only the HTTP 404 error code is relevant. ```text + ``` --- @@ -488,8 +487,8 @@ Obtain an extended description of this server ```json { - "updated_at":"2022-11-03T04:09:07Z", - "content":"

For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.

\n\n

Funding

\n\n

This server is crowdfunded by Patreon donations. For a list of sponsors, see joinmastodon.org.

\n\n

Reporting and moderation

\n\n

When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.

\n\n

We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.

\n\n

Impressum

\n\n

Mastodon gGmbH
\nMühlenstraße 8a
\n14167 Berlin
\nGermany

\n\n

E-Mail-Adresse: hello@joinmastodon.org

\n\n

Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)

\n\n

Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260

\n\n

Handelsregister
\nGeführt bei: Amtsgericht Charlottenburg
\nNummer: HRB 230086 B

\n" + "updated_at": "2022-11-03T04:09:07Z", + "content": "

For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.

\n\n

Funding

\n\n

This server is crowdfunded by Patreon donations. For a list of sponsors, see joinmastodon.org.

\n\n

Reporting and moderation

\n\n

When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.

\n\n

We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.

\n\n

Impressum

\n\n

Mastodon gGmbH
\nMühlenstraße 8a
\n14167 Berlin
\nGermany

\n\n

E-Mail-Adresse: hello@joinmastodon.org

\n\n

Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)

\n\n

Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260

\n\n

Handelsregister
\nGeführt bei: Amtsgericht Charlottenburg
\nNummer: HRB 230086 B

\n" } ``` @@ -550,35 +549,33 @@ Obtain general information about the server. See [api/v2/instance]({{< relref "m ```json { - "uri":"mastodon.social", - "title":"Mastodon", - "short_description":"The original server operated by the Mastodon gGmbH non-profit", - "description":"", - "email":"staff@mastodon.social", - "version":"3.5.3", - "urls":{ - "streaming_api":"wss://mastodon.social" + "uri": "mastodon.social", + "title": "Mastodon", + "short_description": "The original server operated by the Mastodon gGmbH non-profit", + "description": "", + "email": "staff@mastodon.social", + "version": "3.5.3", + "urls": { + "streaming_api": "wss://mastodon.social" }, - "stats":{ - "user_count":812303, - "status_count":38151616, - "domain_count":25255 + "stats": { + "user_count": 812303, + "status_count": 38151616, + "domain_count": 25255 }, - "thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", - "languages":[ - "en" - ], - "registrations":false, - "approval_required":false, - "invites_enabled":true, - "configuration":{ - "statuses":{ - "max_characters":500, - "max_media_attachments":4, - "characters_reserved_per_url":23 + "thumbnail": "https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", + "languages": ["en"], + "registrations": false, + "approval_required": false, + "invites_enabled": true, + "configuration": { + "statuses": { + "max_characters": 500, + "max_media_attachments": 4, + "characters_reserved_per_url": 23 }, - "media_attachments":{ - "supported_mime_types":[ + "media_attachments": { + "supported_mime_types": [ "image/jpeg", "image/png", "image/gif", @@ -605,74 +602,72 @@ Obtain general information about the server. See [api/v2/instance]({{< relref "m "audio/3gpp", "video/x-ms-asf" ], - "image_size_limit":10485760, - "image_matrix_limit":16777216, - "video_size_limit":41943040, - "video_frame_rate_limit":60, - "video_matrix_limit":2304000 + "image_size_limit": 10485760, + "image_matrix_limit": 16777216, + "video_size_limit": 41943040, + "video_frame_rate_limit": 60, + "video_matrix_limit": 2304000 }, - "polls":{ - "max_options":4, - "max_characters_per_option":50, - "min_expiration":300, - "max_expiration":2629746 + "polls": { + "max_options": 4, + "max_characters_per_option": 50, + "min_expiration": 300, + "max_expiration": 2629746 } }, - "contact_account":{ - "id":"1", - "username":"Gargron", - "acct":"Gargron", - "display_name":"Eugen", - "locked":false, - "bot":false, - "discoverable":true, - "group":false, - "created_at":"2016-03-16T00:00:00.000Z", - "note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e", - "url":"https://mastodon.social/@Gargron", - "avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", - "avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", - "header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", - "header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", - "followers_count":118944, - "following_count":305, - "statuses_count":72309, - "last_status_at":"2022-08-24", - "emojis":[ - - ], - "fields":[ + "contact_account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen", + "locked": false, + "bot": false, + "discoverable": true, + "group": false, + "created_at": "2016-03-16T00:00:00.000Z", + "note": "\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e", + "url": "https://mastodon.social/@Gargron", + "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count": 118944, + "following_count": 305, + "statuses_count": 72309, + "last_status_at": "2022-08-24", + "emojis": [], + "fields": [ { - "name":"Patreon", - "value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e", - "verified_at":null + "name": "Patreon", + "value": "\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e", + "verified_at": null } ] }, - "rules":[ + "rules": [ { - "id":"1", - "text":"Sexually explicit or violent media must be marked as sensitive when posting" + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" }, { - "id":"2", - "text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" }, { - "id":"3", - "text":"No incitement of violence or promotion of violent ideologies" + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" }, { - "id":"4", - "text":"No harassment, dogpiling or doxxing of other users" + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" }, { - "id":"5", - "text":"No content illegal in Germany" + "id": "5", + "text": "No content illegal in Germany" }, { - "id":"7", - "text":"Do not share intentionally false or misleading information" + "id": "7", + "text": "Do not share intentionally false or misleading information" } ] } From 94a7463adb04431a0376e1ecb273b84144b00abc Mon Sep 17 00:00:00 2001 From: Emelia Smith Date: Wed, 15 May 2024 17:15:50 +0200 Subject: [PATCH 3/3] Remove vapid_key from Apps API examples, since this property is deprecated on Application entity --- content/en/methods/apps.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/content/en/methods/apps.md b/content/en/methods/apps.md index 85409fd182..0ca521e5bc 100644 --- a/content/en/methods/apps.md +++ b/content/en/methods/apps.md @@ -61,8 +61,7 @@ Store the `client_id` and `client_secret` in your cache, as these will be used t "website": null, "redirect_uri": "urn:ietf:wg:oauth:2.0:oob", "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM", - "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw", - "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" + "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw" } ``` @@ -109,8 +108,7 @@ If the Authorization header was provided with a valid token, you should see your ```json { "name": "test app", - "website": null, - "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" + "website": null } ```