metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jjmeyer0 <...@git.apache.org>
Subject [GitHub] incubator-metron issue #316: METRON-503: Metron REST API
Date Thu, 05 Jan 2017 13:34:54 GMT
Github user jjmeyer0 commented on the issue:

    https://github.com/apache/incubator-metron/pull/316
  
    
    **Project Structure:**
    
    Personally I think the module, `metron-interface`, should be split up into more modules.
I think there should be `metron-rest` and `metron-rest-client`. The idea would be to move
the models into the client module. Specifically the models returned by the endpoints and are
used when making requests. I personally like to to do this because it allows a user to use
the client without having to bring a ton of dependencies onto their classpath. This is assuming
there will eventually be a client module. Does this make sense? Think it is worth doing now?
    
    **Response Behavior:**
    
    I think we should also decide how Metron's APIs handle errors. In the past I have defined
an error response type that was used by all endpoints. It could potentially look something
like:
    
    {
      "responseCode" : 404, 
      "message" : "Could not find parser config.", 
      'fullMessage" : "Could not find parser config with the name: [some name]"
    }
    
    Also, I personally do not like to throw exceptions of type `Exception`. I think we could
do a couple things. We could create a MetronRestException that gets mapped to an error response.
We could also have the service layer use an `Either` type which would either return the response
entity or a set of error responses. Do you all think this is worth talking about now? I think
this is always one of those things that's tough to decide, but should be standard across the
API.
    
    **API Documentation:**
    
    I think it is worth documenting all the different response types for each endpoint. For
example, the endpoint `/api/v1/sensorParserConfigHistory` only describes the response for
a 200 code, but there is also a 404. This can be done by using Swagger's `ApiResponses` annotation.
    
    **API Structure:**
    
    As for API structure there were a few that I thought could potentially be changed. Below
are a few examples. To me it may make sense at some point to have a sensor endpoint. IMO breaking
it up as I did below groups them a bit more nicely (isn't an exhaustive list). What do you
think? 
    
    /api/v1/globalConfig -> /api/v1/global/config
    /api/v1/sensorEnrichmentConfig -> /api/v1/sensor/enrichment/config
    /api/v1/sensorParserConfig -> /api/v1/sensor/parser/config
    /api/v1/sensorParserConfigHistory -> /api/v1/sensor/parser/config/history



---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message