#7208 DOAP API for projects

v1.2.0
closed
nobody
General
2015-08-20
2014-02-21
Dave Brondsema
No

Create a DOAP API endpoint for allura projects. I think the URL should be /rest/p/projectname?doap (open to better suggestions). It should be XML that is similar in format to SourceForge (classic) DOAP files like https://sourceforge.net/api/project/name/vivo/doap as much as possible. A number of fields in that are not applicable to Allura, so just don't include them. It is okay for Allura DOAP to continue to use some of the "sf" namespace elements like environment, database, etc (those are all the trove types of a project), as well as sf:awarded (for awards, use the current Allura award system available via neighborhood admin pages). <maintainer> is for each project Admin and <developer> is for each Developer on the project.

In addition to the basics, each tool should be able provide its own XML/RDF data to include. For example, SourceForge's internal mailman tool could provide <mailing-list> entries and Files tool could provide a <download-page> entry.

Discussion

  • Dave Brondsema
    Dave Brondsema
    2014-02-21

    • Labels: doap, allura-api --> allura-api, 42cc, doap
    • Status: open --> in-progress
     
    • status: in-progress --> code-review
     
  • Closed #549. je/42cc_7208

     
  • Cory Johns
    Cory Johns
    2014-03-03

    • QA: Cory Johns
     
  • Cory Johns
    Cory Johns
    2014-03-03

    Looks good for the most part, but there are a few things to address:

    name should be populated with project.shortname while dc:title should get project.name

    Store the result of self.admins() instead of calling it multiple times in Project.doap()

    Instead of adding a new library to the requirements, we should use xml.etree.ElementTree. For example, the Application.doap() method could be converted to the following:

    def doap(self, parent):
        """App's representation for DOAP API.
    
        :param parent: Element to contain the results
        :type parent: xml.etree.ElementTree.Element or xml.etree.ElementTree.SubElement
        """
        feature = SubElement(parent, 'sf:feature')
        SubElement(feature, 'sf:Feature')
        SubElement(feature, 'name').text = self.config.options.mount_label
        SubElement(feature, 'foaf:page', {'rdf:resource': h.absurl(self.url)})
    

    I'm not sure about selecting the output format. We have some precedent for using a suffix (i.e., /rest/p/proj.doap) in the feeds (e.g., ForgeActivityController.__init__), but that seems like it would be difficult to implement in this case due to requiring modifications to the controller dispatch. I've also read some criticisms of including the output format in the URI, and some people recommend using the Accept: header, but that makes debugging the APIs in the browser more difficult. If adding Accept: header support isn't too difficult, I think that would be worth doing, otherwise, the way it is currently is probably fine.

     
  • Cory Johns
    Cory Johns
    2014-03-03

    • status: code-review --> in-progress
     
  • Dave Brondsema
    Dave Brondsema
    2014-03-03

    .doap looks better to me than ?doap Too bad its difficult though. Maybe not.

    I am -1 on using the Accept: header. I believe it is proper according to HTTP specifications, but it is just not very practical. It's so much easier to work with APIs if you can get what you want with just a URL and no special headers.

     
  • I think we can implement .doap, it shouldn't be that hard.

     
  • Cory Johns
    Cory Johns
    2014-03-05

    I was suggesting allowing Accept: in addition to specifying the format in the URI, but I doubt it's worth bothering with.

    Regarding .doap vs ?doap (or ?format=doap), I read an argument that .doap is significantly "worse" because the URI no longer identifies a resource, but a format / encoding of a resource. But we do have precedent for it, as I noted.

    I'm not really keen on modifying the NeighborhoodRestController._lookup (which is where I think it would need to go to work) with code specific to the format of a single view, even if the code itself is relatively simple. It also raises the question of what happens when someone requests http://sf.net/rest/p/allura.doap/tickets (which, again, indicates that the URI should identify the resource, irrespective of format).

     
    • status: in-progress --> code-review
     
  • Closed #556. Updated je/42cc_7208

    I've left ?doap as is, since other variants even worse.

    I've also deleted Application.additional_doap_entries(), since you can just override Application.doap() in subclass and add as many SubElement's to parent as you want now.

     
  • Cory Johns
    Cory Johns
    2014-03-12

    • status: code-review --> closed
    • Milestone: forge-backlog --> forge-mar-21
     
  • Dave Brondsema
    Dave Brondsema
    2014-03-25

    A few details that should be changed:

    rdf:about= is wrong, has "vivo" hard-coded in it. It should be the fully qualified doap URL plus "#" like "http://DOMAIN/rest/p/PROJECT?doap#"

    Remove <sf:id>. To maintain consistency with SourceForge id values in its old DOAP endpoints, SourceForge should provide that field from an internal tool.

    <sf:private /> comes through with no value.

    <shortdesc> should use the summary field and <description> should use the short_description field. (The description field isn't used. Confusing, eh?)

     
  • Dave Brondsema
    Dave Brondsema
    2014-03-25

    • status: closed --> in-progress
    • QA: Cory Johns --> nobody
     
  • Dave Brondsema
    Dave Brondsema
    2014-03-26

    And also <created> is missing. It should be YYYY-MM-DD of the project registration date.

     
  • Closed #566. Force-pushed je/42cc_7208

     
    • status: in-progress --> code-review
     
  • Dave Brondsema
    Dave Brondsema
    2014-04-03

    • status: code-review --> closed
    • QA: Dave Brondsema
     
  • Dave Brondsema
    Dave Brondsema
    2015-01-05

    • Milestone: unreleased --> asf_release_1.2.0