3874 V4 API Documentation

[albertisfu]

According to our talk, I have added support to handle version 4 of the API.

• Considering most of the endpoints won't change their specifications and the only change is the version, I added a VersionedTemplateView which takes the version from the URL and uses it to select the template according to the version. It also passes the version to the context. So we can avoid duplicated templates when this is the only change.

Most endpoints now use the same template -vlatest.html, and only the version changes within the template where required or rendered.

In case we need to create a custom template for an endpoint to notice differences between v3 and v4, that can be done by creating a template for v3, for instance: search-api-docs-v3.html, and using search-api-docs-vlatest.html for v4. Like the search case where for now, I copied the HTML of search-api-docs-v3.html to search-api-docs-vlatest.html.

The other template that I copied was the base API template. I created rest-docs-v3.html and rest-docs-vlatest.html can be used to describe changes for v4.

Let me know if additional tweaks are required.

[mlissner]

Sorry to take a little time reviewing this. Code-wise this is great, nice solution, but when this merges, we'll officially launch v4, so we need to do some more work to get the remaining pages ready before then.

The migration guide is a nice-to-have. It'd be nice to launch v4 with that in place, but before we merge this, we at least need to update the documentation so that the v4 documentation is 100% correct for all the changes we've made.

I think this might be a good step for @s-taube to work on, to get this over the line and merged. That will officially launch the new API, and then it'll just be about turning off the old Solr stuff, and migrating people to the new one.

So: This looks good and is safe to merge, but we want to add to it before we do.

Thanks Alberto.

[CLAassistant]

All committers have signed the CLA.

[s-taube]

@albertisfu , I was going to update the example results on the search api page, because some of the fields in the given example have changed or been removed. For example, under “Basic Usage,” the returned results are for type=o (type: lead-opinion), and the now-removed fields of source, status_exact, and non_participating_judge_ids are listed in the results (though, non_participating_judge_ids is “null,” which may be okay. Not sure.).

However, when I try to get v4 results via the link https://www.courtlistener.com/api/rest/v4/search/?q=foo, source and non_participating_judge_ids are still listed.

Do you have any guidance on what updates should be made (if any) to the results under “Basic Usage” on the search API page?

[albertisfu]

Do you have any guidance on what updates should be made (if any) to the results under “Basic Usage” on the search API page?

Yeah, in this case, I see that the page you're editing is help/api/rest/v3/search/, which references the V3 API.

You can find the example results here: https://www.courtlistener.com/api/rest/v3/search/?q=foo
(You need to be logged into CourtListener and have staff privileges to view this page with the changes described in the migration guide, as this feature is now only enabled for staff members.)

Here is an example:

{
   "count":2343,
   "next":"https://www.courtlistener.com/api/rest/v3/search/?page=2&q=foo",
   "previous":null,
   "results":[
      {
         "absolute_url":"/opinion/6613686/foo-v-foo/",
         "attorney":"",
         "author_id":null,
         "caseName":"Foo v. Foo",
         "citation":[
            "101 Haw. 235",
            "65 P.3d 182"
         ],
         "citeCount":0,
         "cites":null,
         "cluster_id":6613686,
         "court":"Hawaii Intermediate Court of Appeals",
         "court_citation_string":"Haw. App.",
         "court_exact":"hawapp",
         "court_id":"hawapp",
         "dateArgued":null,
         "dateFiled":"2003-01-10T00:00:00-08:00",
         "dateReargued":null,
         "dateReargumentDenied":null,
         "date_created":"2022-06-26T16:24:18.931912-07:00",
         "docketNumber":"24158",
         "docket_id":63544014,
         "download_url":null,
         "id":6489975,
         "joined_by_ids":null,
         "judge":"",
         "lexisCite":"",
         "local_path":null,
         "neutralCite":"",
         "panel_ids":null,
         "per_curiam":false,
         "scdb_id":"",
         "sibling_ids":[
            6489975
         ],
         "snippet":"\nAffirmed in part, reversed in part, vacated and remanded\n",
         "status":"Precedential",
         "suitNature":"",
         "timestamp":"2024-06-24T14:14:41.408206-07:00",
         "type":"020lead"
      }
   ]
}

As you can see, the following fields are not present: source, status_exact, non_participating_judge_ids, pagerank, and caseNameShort. There is also a new field: date_created, as described in the migration guide.

For V4, the example can be extracted from the link you shared:
https://www.courtlistener.com/api/rest/v4/search/?q=foo

The difference from V3, is that source and non_participating_judge_ids are still available in the response because these fields were moved from the Opinions to the cluster field level. That's why they're not shown in V3, which displays Opinions instead of OpinionCluster.

[mlissner]

@s-taube, I think you should be marked as staff in CL, but let me know if not.

[s-taube]

On v3 API pages, we want to let people know v4 is now available. And on v4 pages, we want to link people back to v3 in case they didn’t migrate yet.

@albertisfu, on api/rest/v3, can you add an alert that links people to the latest version? (I assume you would have made this change anyway, for consistency with api/rest/v2 and api/rest/v1, which both have the alert “These notes are for a version of the API that has been deprecated...please use the latest version...")

At the top of rest-docs-vlatest, I just added an alert that links people back to the change log in case they want to access v3 documentation.

[albertisfu]

@s-taube Of course, I’ve added the alert you mentioned: These notes are for a version of the API that has been deprecated...please use the latest version... on the v3 documentation page: /help/api/rest/v3/ following consistency with /help/api/rest/v2/ and /help/api/rest/v1/

This alert links to /help/api/rest/

Just one question: You mentioned this alert should also appear on /api/rest/v3/, similar to v2 and v1.

On /api/rest/v2/ and /api/rest/v1/, we currently return the following API response for these endpoints:

{"meta": {"status": "This endpoint is deprecated. Please upgrade to the newest version of the API."}, "objects": []}

If we add this response now, v3 will be disabled completely.

However, could we add an additional key to the v3 endpoints response to alert users about its future deprecation?

{
    "count": 27,
    "next": "http://localhost:8000/api/rest/v3/dockets/?page=2",
    "previous": null,
     "stauts": "This endpoint will be deprecated soon. Please upgrade to the latest version of the API.",
    "results": [
        {

Would this be helpful? @mlissner

[mlissner]

v3 isn't going to be deprecated particularly soon, so /api/rest/v3/, should stay how it is. No need to add a status message to it; I don't think anybody would see it, and we'll get people moved by email or other ways.

On the warning, I think a better message is:

These notes are for a version of the API that is deprecated. New implementations should use the [latest version of the API][api] and existing software [should be upgraded][up]. These notes are maintained to help with migrations.

[api]: /help/api/rest/
[up]: /help/api/migration-docs/ (wherever this link winds up)

I'd love to disable v3, but it's going to take a very long time. The best we can really do is switch v3 of search over to Elastic with some minor breakage.

[albertisfu]

Great! I've updated the warning message:

Since we don’t have a migration-docs route in this PR yet, I haven’t added the correct link. I’m not sure if @s-taube is planning to open a separate PR for the migration guide, or if we should create the view in this one?

[s-taube]

@albertisfu I won't add a separate PR, and yes, create the view in this one.

[albertisfu]

Sure, I've added the migration guide view and template. It's available at /help/api/migration-docs/

The template is migration-docs.html, which currently only includes the base docs structure, and the content is empty.

I’ve linked this page in the V3 docs warning message.

Let me know if anything else is needed.

[mlissner]

Thanks Alberto. Would it make more sense to put the migration guide in the v4 namespace? Maybe /help/api/v4/migration-guide/, say? Sorry, I didn't mean to suggest the other URL earlier, but putting it here will help when we have our next guide in the future.

Also, do you think you could convert the Google doc to HTML and put it in the guide? I think you'll have a better chance of getting all the details right, since you've got proper HTML editors and such?

[albertisfu]

Of course. I'll apply these changes.

[albertisfu]

@s-taube I've added the V4 API Migration Guide HTML along with its Table of Contents based on the Google document we have. It's located at /help/api/v4/migration-guide/

I believe we just need to set the date, which currently appears as: XXXDATEXXX.

Let me know if any additional adjustments are needed.

[mlissner]

I know we're not done yet, but I'm really excited to be pushing this out. Thank you both!