Document submodule handling in Repo Contents API

jasonrudolph · jasonrudolph · commit 81c7e58e6782 · 2013-04-30T05:20:46.000-04:00
diff --git a/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md b/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md
@@ -0,0 +1,39 @@
+---
+kind: change
+title: Improved Support for Submodules in the Repository Contents API
+created_at: 2013-04-30
+author_name: jasonrudolph
+---
+
+When you view a repository with a submodule on github.com, you get useful links and information for the submodule.
+
+[![Repository Contents with Submodule](/images/posts/submodule-links.png)][screenshot]
+
+Today we're making that data available in the [Repository Contents API][docs].
+
+<pre class="terminal">
+curl https://api.github.com/repos/jquery/jquery/contents/test/qunit
+
+{
+  "name": "qunit",
+  "path": "test/qunit",
+  "type": "submodule",
+  "submodule_git_url": "git://github.com/jquery/qunit.git",
+  "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
+  "size": 0,
+  "url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+  "git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+  "html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+  "_links": {
+    "self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+    "git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+    "html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
+  }
+}
+</pre>
+
+If you have any questions or feedback, please drop us a line at
+[support@github.com](mailto:support@github.com?subject=Submodules in Repository Contents API).
+
+[docs]: /v3/repos/contents/#get-contents
+[screenshot]: /images/posts/submodule-links.png
diff --git a/content/v3/repos/contents.md b/content/v3/repos/contents.md
@@ -35,7 +35,7 @@ This method returns the contents of a file or directory in a repository.
     GET /repos/:owner/:repo/contents/:path
 
 Files and symlinks support [a custom media type](#custom-media-types) for getting the raw content.
-Directories do _not_ support custom media types.
+Directories and submodules do _not_ support custom media types.
 
 *Notes*:
 
@@ -69,6 +69,16 @@ Otherwise, the API responds with a hash describing the symlink itself:
 <%= headers 200 %>
 <%= json :symlink_content %>
 
+### Response if content is a submodule
+
+<%= headers 200 %>
+<%= json :submodule_content %>
+
+The `submodule_git_url` identifies the location of the submodule repository, and the `sha` identifies a specific commit within the submodule repository.
+Git uses the given URL when cloning the submodule repository, and checks out the submodule at that specific commit.
+
+If the submodule repository is not hosted on github.com, the Git URLs (`git_url` and `_links["git"]`) and the github.com URLs (`html_url` and `_links["html"]`) will have null values.
+
 ## Get archive link
 
 This method will return a `302` to a URL to download a tarball
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -1021,6 +1021,23 @@ def text_html(response, status, head = {})
       },
     }
 
+    SUBMODULE_CONTENT = {
+      "type" => "submodule",
+      "submodule_git_url" => "git://github.com/jquery/qunit.git",
+      "size" => 0,
+      "name" => "qunit",
+      "path" => "test/qunit",
+      "sha" => "6ca3721222109997540bd6d9ccd396902e0ad2f9",
+      "url" => "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+      "git_url" => "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+      "html_url" => "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+      "_links" => {
+        "git" => "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
+        "self" => "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
+        "html" => "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
+      }
+    }
+
     DIRECTORY_CONTENT = [
       {
         "type" => "file",
diff --git a/static/images/posts/submodule-links.png b/static/images/posts/submodule-links.png
