Fix nomenclature in example requests and responses

openverse-api/catalog/api/docs/audio_docs.py

@@ -9,19 +9,19 @@
     MediaComplain,
 )
 from catalog.api.examples import (
-    audio_search_curl,
+    audio_search_list_curl,
     audio_search_200_example,
     audio_search_400_example,
-    recommendations_audio_read_curl,
-    recommendations_audio_read_200_example,
-    recommendations_audio_read_404_example,
+    audio_stats_curl,
+    audio_stats_200_example,
     audio_detail_curl,
     audio_detail_200_example,
     audio_detail_404_example,
-    audio_stats_curl,
-    audio_stats_200_example,
-    report_audio_curl,
-    audio_report_create_201_example,
+    audio_related_curl,
+    audio_related_200_example,
+    audio_related_404_example,
+    audio_complain_curl,
+    audio_complain_201_example,
 )
 from catalog.api.serializers.audio_serializers import (
     AudioSearchRequestSerializer,
@@ -62,7 +62,7 @@ class AudioSearch(MediaSearch):
     code_examples = [
         {
             'lang': 'Bash',
-            'source': audio_search_curl,
+            'source': audio_search_list_curl,
         },
     ]
 
@@ -155,20 +155,20 @@ class AudioRelated(MediaRelated):
     responses = {
         "200": openapi.Response(
             description="OK",
-            examples=recommendations_audio_read_200_example,
+            examples=audio_related_200_example,
             schema=AudioSerializer
         ),
         "404": openapi.Response(
             description="Not Found",
-            examples=recommendations_audio_read_404_example,
+            examples=audio_related_404_example,
             schema=NotFoundErrorSerializer
         )
     }
 
     code_examples = [
         {
             'lang': 'Bash',
-            'source': recommendations_audio_read_curl,
+            'source': audio_related_curl,
         },
     ]
 
@@ -193,15 +193,15 @@ class AudioComplain(MediaComplain):
     responses = {
         "201": openapi.Response(
             description="OK",
-            examples=audio_report_create_201_example,
+            examples=audio_complain_201_example,
             schema=AudioReportSerializer
         )
     }
 
     code_examples = [
         {
             'lang': 'Bash',
-            'source': report_audio_curl,
+            'source': audio_complain_curl,
         }
     ]
 

openverse-api/catalog/api/docs/image_docs.py

@@ -10,22 +10,22 @@
     MediaComplain,
 )
 from catalog.api.examples import (
-    image_search_curl,
+    image_search_list_curl,
     image_search_200_example,
     image_search_400_example,
-    recommendations_images_read_curl,
-    recommendations_images_read_200_example,
-    recommendations_images_read_404_example,
+    image_stats_curl,
+    image_stats_200_example,
     image_detail_curl,
     image_detail_200_example,
     image_detail_404_example,
-    image_stats_curl,
-    image_stats_200_example,
-    report_image_curl,
-    images_report_create_201_example,
-    oembed_list_curl,
-    oembed_list_200_example,
-    oembed_list_404_example,
+    image_related_curl,
+    image_related_200_example,
+    image_related_404_example,
+    image_complain_curl,
+    image_complain_201_example,
+    image_oembed_curl,
+    image_oembed_200_example,
+    image_oembed_404_example,
 )
 from catalog.api.serializers.error_serializers import (
     InputErrorSerializer,
@@ -68,7 +68,7 @@ class ImageSearch(MediaSearch):
     code_examples = [
         {
             'lang': 'Bash',
-            'source': image_search_curl,
+            'source': image_search_list_curl,
         },
     ]
 
@@ -161,20 +161,20 @@ class ImageRelated(MediaRelated):
     responses = {
         "200": openapi.Response(
             description="OK",
-            examples=recommendations_images_read_200_example,
+            examples=image_related_200_example,
             schema=ImageSerializer
         ),
         "404": openapi.Response(
             description="Not Found",
-            examples=recommendations_images_read_404_example,
+            examples=image_related_404_example,
             schema=NotFoundErrorSerializer
         )
     }
 
     code_examples = [
         {
             'lang': 'Bash',
-            'source': recommendations_images_read_curl
+            'source': image_related_curl
         }
     ]
 
@@ -199,15 +199,15 @@ class ImageComplain(MediaComplain):
     responses = {
         "201": openapi.Response(
             description="OK",
-            examples=images_report_create_201_example,
+            examples=image_complain_201_example,
             schema=ImageReportSerializer
         )
     }
 
     code_examples = [
         {
             'lang': 'Bash',
-            'source': report_image_curl,
+            'source': image_complain_curl,
         }
     ]
 
@@ -234,20 +234,20 @@ class ImageOembed:
     responses = {
         "200": openapi.Response(
             description="OK",
-            examples=oembed_list_200_example,
+            examples=image_oembed_200_example,
             schema=OembedSerializer
         ),
         "404": openapi.Response(
             description="Not Found",
-            examples=oembed_list_404_example,
+            examples=image_oembed_404_example,
             schema=NotFoundErrorSerializer
         )
     }
 
     code_examples = [
         {
             'lang': 'Bash',
-            'source': oembed_list_curl,
+            'source': image_oembed_curl,
         },
     ]
 

openverse-api/catalog/api/examples/__init__.py

@@ -1,37 +1,39 @@
 from catalog.api.examples.audio_requests import (
+    audio_search_list_curl,
     audio_search_curl,
-    recommendations_audio_read_curl,
-    audio_detail_curl,
     audio_stats_curl,
-    report_audio_curl,
+    audio_detail_curl,
+    audio_related_curl,
+    audio_complain_curl,
 )
 from catalog.api.examples.audio_responses import (
     audio_search_200_example,
     audio_search_400_example,
+    audio_stats_200_example,
     audio_detail_200_example,
     audio_detail_404_example,
-    recommendations_audio_read_200_example,
-    recommendations_audio_read_404_example,
-    audio_report_create_201_example,
-    audio_stats_200_example,
+    audio_related_200_example,
+    audio_related_404_example,
+    audio_complain_201_example,
 )
 from catalog.api.examples.image_requests import (
+    image_search_list_curl,
     image_search_curl,
-    recommendations_images_read_curl,
-    image_detail_curl,
     image_stats_curl,
-    report_image_curl,
-    oembed_list_curl,
+    image_detail_curl,
+    image_related_curl,
+    image_complain_curl,
+    image_oembed_curl,
 )
 from catalog.api.examples.image_responses import (
     image_search_200_example,
     image_search_400_example,
+    image_stats_200_example,
     image_detail_200_example,
     image_detail_404_example,
-    recommendations_images_read_200_example,
-    recommendations_images_read_404_example,
-    oembed_list_200_example,
-    oembed_list_404_example,
-    images_report_create_201_example,
-    image_stats_200_example,
+    image_related_200_example,
+    image_related_404_example,
+    image_complain_201_example,
+    image_oembed_200_example,
+    image_oembed_404_example,
 )

openverse-api/catalog/api/examples/audio_requests.py

@@ -1,3 +1,11 @@
+import os
+
+token = os.getenv('AUDIO_REQ_TOKEN', 'DLBYIcfnKfolaXKcmMC8RIDCavc2hW')
+origin = os.getenv('AUDIO_REQ_ORIGIN', 'https://api.openverse.engineering')
+
+auth = f'-H "Authorization: Bearer {token}"' if token else ''
+identifier = '440a0240-8b20-49e2-a4e6-6fee550fcc41'
+
 syntax_examples = {
     "using single query parameter":
         'test',
@@ -20,29 +28,37 @@
         'theatre~1',
 }
 
-audio_search_curl = '\n\n'.join([
-    (f'# Example {index}: Search for audio {purpose}\n'
-     'curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" '
-     f'https://api.openverse.engineering/v1/audio?q={syntax}')
-    for (index, (purpose, syntax)) in enumerate(syntax_examples.items())
-])
+audio_search_list_curl = '\n'.join(f"""
+# Example {index}: Search for audio {purpose}
+curl {auth} "{origin}/v1/audio/?q={syntax}"
+""" for (index, (purpose, syntax)) in enumerate(syntax_examples.items()))
 
-recommendations_audio_read_curl = """
-# Get related audio files for audio ID 7c829a03-fb24-4b57-9b03-65f43ed19395
-curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" http://api.openverse.engineering/v1/recommendations/audio/7c829a03-fb24-4b57-9b03-65f43ed19395
-"""  # noqa
+audio_search_curl = f"""
+# Search for music titled "Friend" by Rob Costlow
+curl {auth} "{origin}/v1/audio/?title=Friend&creator=Rob%20Costlow"
+"""
 
-audio_detail_curl = """
-# Get the details of audio ID 7c829a03-fb24-4b57-9b03-65f43ed19395
-curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" http://api.openverse.engineering/v1/audio/7c829a03-fb24-4b57-9b03-65f43ed19395
-"""  # noqa
-
-audio_stats_curl = """
+audio_stats_curl = f"""
 # Get the statistics for audio sources
-curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" http://api.openverse.engineering/v1/audio/stats
-"""  # noqa
+curl {auth} "{origin}/v1/audio/stats/"
+"""
+
+audio_detail_curl = f"""
+# Get the details of audio ID {identifier}
+curl {auth} "{origin}/v1/audio/{identifier}/"
+"""
+
+audio_related_curl = f"""
+# Get related audio files for audio ID {identifier}
+curl {auth} "{origin}/v1/audio/{identifier}/related/"
+"""
 
-report_audio_curl = """
-# Report an issue about audio ID 7c829a03-fb24-4b57-9b03-65f43ed19395
-curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" -d '{"reason": "mature", "description": "This audio contains sensitive content"}' https://api.openverse.engineering/v1/audio/7c829a03-fb24-4b57-9b03-65f43ed19395/report
+audio_complain_curl = f"""
+# Report an issue about audio ID {identifier}
+curl \\
+  -X POST \\
+  -H "Content-Type: application/json" \\
+  {auth} \\
+  -d '{{"reason": "mature", "description": "This audio contains sensitive content"}}' \\
+  "{origin}/v1/audio/{identifier}/report/"
 """  # noqa