Move API entries to separate namespaces?

[wrygiel]

APIs are being described in separate repositories and use separate namespaces, and I consider it a good design decision.

However, elements describing these APIs in the manifest file (children of <apis-implemented> element) all use the Discovery's namespace currently. So, whenever a new API is added, the Discovery document needs to be modified. So, perhaps it would be better to move these manifest entries to their respective repositories?

Note, that the manifest file already allows us to use entries from different namespaces under the <apis-implemented> element:

<xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="strict">
    <xs:annotation>
        <xs:documentation>
            We allow for the manifest to describe external APIs too (unrelated to the EWP
            Project, but compatible with the EWP Network). It is RECOMMENDED that all such
            APIs are documented in a similar fashion to the one used within the EWP
            Project.
        </xs:documentation>
    </xs:annotation>
</xs:any>

[wrygiel]

This way, each API specification will be able to describe itself completely (including the format of the entry required in the manifest file).

[georgschermann]

+1, this worked well in a project i did a few years ago

[mikesteez]

Do you have an example of the proposed solution?

[wrygiel]

No, but I can prepare one.

[wrygiel]

Posted an example XSD here (for the Departments API):

https://github.com/erasmus-without-paper/ewp-specs-api-departments/blob/3dbbf565aa0ef2aa69d6479e7e80661f1ce26ae3/manifest-entry.xsd

And here's a valid manifest with proper entry:

<manifest
    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-discovery/tree/stable-v2"
    xmlns:m="https://github.com/erasmus-without-paper/ewp-specs-api-discovery/tree/stable-v2"
>
    <dev-email>admin1@example.com</dev-email>
    <dev-notes>It's not a real manifest. Just an example.</dev-notes>
    <apis-implemented>
        <discovery version="2.0.0">
            <dev-email>admin2@example.com</dev-email>
            <dev-email>admin3@example.com</dev-email>
            <url>https://example.com/manifest.xml</url>
        </discovery>
        <departments xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-departments/blob/master/manifest-entry.xsd">
            <m:dev-email>admin4@example.com</m:dev-email>
            <url>https://example.com/departments/</url>
        </departments>
    </apis-implemented>
    <institutions-covered>
        <hei id="uw.edu.pl">
            <other-id type="pic">999572294</other-id>
            <other-id type="erasmus">PL WARSZAW01</other-id>
            <name xml:lang="en">University of Warsaw</name>
        </hei>
    </institutions-covered>
</manifest>

The manifest file becomes more verbose, and perhaps a little more difficult to read (somewhat cluttered with various namespaces). But the entire definition of the Departments API entry is kept in the Departments API repository.

[mikesteez]

I like it! We could have a common API for each API to implement, such as dev-email, which then each API would have to use. Another thought, each individual HEI in the manifest will have to implement all APIs specified. For Sweden this will be the default case, but is it applicable to all countries?

[wrygiel]

I like it! We could have a common API for each API to implement, such as dev-email, which then each API would have to use.

Currently both dev-email and dev-notes are optional, and it is not required for API entries to "inherit" from discovery:ApiEntry, but we can recommend it.

Another thought, each individual HEI in the manifest will have to implement all APIs specified. For Sweden this will be the default case, but is it applicable to all countries?

That's a separate issue. I will move it into a separate thread (see here).

[wrygiel]

Two votes for, none against. I'll try this approach on all other APIs and if it works, I'll commit the changes to all master branches.

[wrygiel]

Added manifest-entry.xsd files for each API. Released a new version of the Discovery API (diff). Everything seems to be in order, I think!

[wrygiel]

And here's a diff of related changes in the common-types.xsd file.