Some feedback/doubts on the API Endpoint

[smileBeda]

I have downloaded and installed the directory plus created a dummy plugin entry (using one of my existing GitHub Plugins). I am mostly interested in the REST API endpoint so to integrate the CP Directory within CP (through my plugin). Thus I loaded the REST API Endpoint and I got this after filling in the Custom Fields manually that I saw are expected.

[
  {
    "id" : 32,
    "categories" : [
      3
    ],
    "modified" : "2022-08-16T03:52:52",
    "template" : "",
    "excerpt" : {
      "rendered" : "<p>Content<\/p>",
      "protected" : false
    },
    "date_gmt" : "2022-08-16T03:27:20",
    "author" : 1,
    "link" : "https:\/\/classicpress-directory.mamp\/plugins\/tukutoi-search-and-filter\/",
    "type" : "plugin",
    "title" : {
      "rendered" : "TukuToi Search &amp; Filter"
    },
    "_links" : {
      "author" : [
        {
          "embeddable" : true,
          "href" : "https:\/\/classicpress-directory.mamp\/wp-json\/wp\/v2\/users\/1"
        }
      ],
      "curies" : [
        {
          "name" : "wp",
          "href" : "https:\/\/api.w.org\/{rel}",
          "templated" : true
        }
      ],
      "collection" : [
        {
          "href" : "https:\/\/classicpress-directory.mamp\/wp-json\/wp\/v2\/plugins"
        }
      ],
      "self" : [
        {
          "href" : "https:\/\/classicpress-directory.mamp\/wp-json\/wp\/v2\/plugins\/32"
        }
      ],
      "wp:term" : [
        {
          "taxonomy" : "category",
          "embeddable" : true,
          "href" : "https:\/\/classicpress-directory.mamp\/wp-json\/wp\/v2\/categories?post=32"
        }
      ],
      "about" : [
        {
          "href" : "https:\/\/classicpress-directory.mamp\/wp-json\/wp\/v2\/types\/plugin"
        }
      ],
      "wp:attachment" : [
        {
          "href" : "https:\/\/classicpress-directory.mamp\/wp-json\/wp\/v2\/media?parent=32"
        }
      ]
    },
    "date" : "2022-08-16T03:27:20",
    "slug" : "tukutoi-search-and-filter",
    "featured_media" : 0,
    "guid" : {
      "rendered" : "https:\/\/classicpress-directory.mamp\/?post_type=plugin&#038;p=32"
    },
    "meta" : {
      "update_uri" : "https:\/\/github.com\/TukuToi\/tukutoi-search-and-filter\/releases\/download\/2.29.1\/tukutoi-search-and-filter.zip",
      "slug" : "tukutoi-search-and-filter",
      "download_link" : "https:\/\/github.com\/TukuToi\/tukutoi-search-and-filter\/releases\/download\/2.29.1\/tukutoi-search-and-filter.zip",
      "cp_version" : "1",
      "requires_php" : "7.0.0",
      "current_version" : "2.29.1",
      "git_provider" : "GitHub"
    },
    "modified_gmt" : "2022-08-16T03:52:52",
    "status" : "publish",
    "content" : {
      "rendered" : "<p>Content<\/p>",
      "protected" : false
    }
  }
]

I saw a couple issues with this information and have a couple doubts.

1. categories returns an array of IDs. It would be better to pass a slug and human name because when a third party listens to this data and wants to show what category the plugin is tagged with, they will not know what 3 (the ID) is (they would have to somehow query back the main site to find out what category ID 3 is exactly.)
2. Similar, with the author - it passes the ID (1 in my case). It should pass the name (possibly GitHub user/account name). Perhaps that will be addressed here?
3. The REST API adds a template key which is empty. Not sure that is intended, and for what it is helpful?
4. In the section links I was not clear about what this is. It seems not needed to me? It points to old WP, and has no relevant information.

   "curies" : [
       {
         "name" : "wp",
         "href" : "https:\/\/api.w.org\/{rel}",
         "templated" : true
       }
     ],

   (Similar for collection, self, wp:term, about and wp:attachment)

5. There's a section featured_media which also seems not needed to me or I misunderstand its purpose.
6. Meta section update_uri - I am not sure what it is for (since we have a download_link already).
7. The meta section has slug (but we already have slug from the post data). Is this intentionally duplicated?

I had to fill in the information manually, I suspect it should however pull most of this information (description, version, php requirements, author, etc) from Git?

Thanks!!

[KTS915]

What you currently see are simply the default data provided by the REST API plus additional metadata. Much of this isn't necessary but, until someone has built the integration — two people have offered but it's not ready yet — I am reluctant to remove anything. Once we know definitively what we need, I can either remove all the other fields or else re-create a new endpoint with precisely what we need. (The latter option would just involve a change of URL for those attempting to use it.)

On specifics:

• My testing suggested that the default slug field was often not the right value for our purposes, so the correct one is the one in the metadata.
• It looks like I should add a couple of new fields to provide names for both authors and categories (and slugs for the latter too). I will see if I can do that sometime later this week.
• The description is the content field (with the excerpt field providing a short summary).
• CP and PHP versions are provided already in the meta fields. Let me know if you didn't see them. (The plugins in there were uploaded before we settled on the appropriate schema.)

[smileBeda]

Sounds good for me @KTS915

just one question. Why are we waiting on core integration, if the integration already exists in form of the plugin? It’s working with existing directory and with GitHub, and I’m about to integrate your new api too.

i mean, I know how folks talk and don’t do. But this one is done. It needs the plugin to be either added as a core plugin or a suggested plugin.

I’ve suggested this in past to Viktor as well, and @xxsimoxx and others agreed with the idea.

this would also allow to actually gather some experience on the (new) api if it gets online and amend it until good. And then once core has an integration we can literally drop the plugin and deliver in core.

it would also avoid having to „bump“ semver, as it wouldn’t be a major change at all.

[KTS915]

I think you've misunderstood a little. Having built the new Directory, I'm certainly not keen to have it just wait around until something else is done that might take a long time!

We aren't waiting for someone to build the integration into core before the new Directory can go live. My above comment about core integration was only to explain why the current REST API endpoints expose the data they do.

My next task is actually to import all the data from the current directory into the test site. Unfortunately, I have received that only in the form of two MySQL dumps. I have cleaned up one of them, but some of the necessary data is missing from it. When I've got that added, then I can import it, and then I'll do the same with the second one.

Once that's done, which is probably going to take a couple of weeks, and the changes to developer and category names/slugs are done, and testing shows that all works fine, then I think (a) we go ahead with replacing the current directory and (b) we go with what we have to access it. If core integration is done by then, great. But my guess (like yours) is that that's unlikely so, like @xxsimoxx, I'm currently expecting to be using your plugin.

[smileBeda]

OK, makes sense to me.

I will leave this ticket open since we have the categories and names to be added, so we can as well use this ticket for tracking that. Feel free to close it though, if you prefer single tasks.

I will add a new layer to my plugin integrating this new API (it will basically just start working whenever the api is online) Adding, removing or changing specific endpoint keys is not a lot of hassle so even if things change, no problem.

PS: To check if the new API is online, all I will do is check if the wp-json URL returns response. That will tell me if the new API is online. Assuming of course, the URL of the dir stays the same. So my plugin will actually switch automatically to the new API as soon that starts responding.

[KTS915]

Thanks, that sounds good to me. I'm going to leave this Issue open, so we can track progress here. I don't see any need to fragment it into several smaller things.

[KTS915]

I have now imported all the plugins we currently have in the original directory, together with their developers. Some don't have a proper download link, so I have them set as draft and they aren't available via the REST API. I will need to contact their developers to see about fixing this (but then I have to contact all the developers about the headers requirements).

I have also tweaked the fields that are now exposed in the REST API. @smileBeda Could you check whether you now see everything you want and nothing you don't? (FYI, many of the plugins will have the slug field as blank. That's the next thing I have to complete manually, because I found that the exported data can't be trusted.)

[KTS915]

Update: the slug meta field has now been filled for each plugin.

[xxsimoxx]

Update: the slug meta field has now been filled for each plugin.

Great! This closes #35.