I have a customer that has a specific API design I am required to comply with. The logic I host with my WEB API code allows the customer to make simple changes to a resource that exists on my system (change, delete etc.).
The interface is very simple:
public IHttpActionResult Post(OpRequest opRequest)
public class OpRequest
{
public string op { get; set; }
public string data { get; set; }
}
Based on the value of "op", i parse "data" to complete the operation.
My question is related to the Content-type header in their request. They do not send a Content-Type header at all, but the actual data they POST is "application/x-www-form-urlencoded" for some requests and "application/json". for other requests. Works fine when they send urlencoded, but throws "415 unsupported media" error when they send JSON.
My thought is that I need to intercept their request, detect the content-type and set it before it reaches my logic, but I am not certain how to do that. I must use a single operation to accommodate all Content-types. Is this possible?
Related
Our team is looking for a convenient way to implement versioning in our ServiceStack API implementation.
I've read the articles:
ServiceStack: RESTful Resource Versioning
https://docs.servicestack.net/versioning#implicit-versioning
ServiceStack versioning - how to customize the request deserialization based on versioning
But I don't get a practical way of working for our system.
I've made a list of changes that could happen in the lifetime of the application:
No breaking changes:
Add a new service
Add a new property to an existing request DTO
Add a new property to an existing response DTO
Add a response to an existing (void) request DTO
Breaking changes:
Remove a service. This breaks the client if the service will be called.
Remove a property of an existing request DTO. May not break, but it will be ignored in
the service, thus the response may differ.
Remove a property of an existing response DTO. This breaks if the calling client uses the property.
Remove HTTP verbs. Replace Any with the desired GET, POST, PUT, DELETE, etc. verbs.
Different semantic meanings of service. Same request name, but different behaviour.
Combinations of breaking changes:
Renaming a service. Thus adding a new service and removing the old one.
Rename a property of an existing request DTO.
Rename a property of an existing response DTO.
Split up property of an existing request DTO.
Split up property of an existing response DTO.
We deliver a new release twice a year. Our naming scheme is very simple and looks like:
2020.1.0
2020.2.0
2021.1.0
2021.2.0
xxxx.x.0
We have service packs within the releases. Service packs cannot contain database changes and breaking API changes. The naming scheme is simple:
2020.1.1
2020.1.2
2020.1.3
2020.1.x
2021.1.1
2021.1.2
2021.1.x
Our client and server apps are delivered at the same time on a customer site. Thus with our software delivery, we update all the software at once. No problems so far.
The problem we have has to do with partners and customers who are using the API and may face breaking changes.
We do not want a partner or customer to force their software simultaneously when we update our software at the customer site. There should be some grace period where the partner or customer can update their clients of our API.
We have the following idea:
Partner en customer client develops against a specific version of our API by giving the release version number. I.e. 20201 (=2020.1) in the header, url or querystring parameter (which is best/supported?).
ServiceStack in our implementation should notice the version specified by the client and let it discovers only the available APIs which belong to that version. Thus if our software is version 2021.2, then it should 'downgrade' its API exploration to the specified version. The idea is that every request DTO and response DTO has a version property with a similar versioning strategy as with aspnet-api-versioning (https://github.com/dotnet/aspnet-api-versioning/wiki).
I've tried to experiment with the current capabilities of ServiceStack in the following example.
// ServiceStack configuration in AppHost
public override void Configure(Funq.Container container)
{
SetConfig(new HostConfig
{
ApiVersion = "20231"
});
var nativeTypes = GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddImplicitVersion = 20231;
}
public class Project
{
public int ID { get; set; }
public Guid GlobalID { get; set; }
public string Number { get; set; }
public string Name { get; set; }
public string Description1 { get; set; }
public string Description2 { get; set; }
public string City { get; set; }
public bool Active { get; set; }
}
[Route("/projects", "GET POST")]
public class GetProjects : IReturn<List<Project>>
{
public string SearchCriteria { get; set; }
public int PageSize { get; set; } = Constants.DefaultPageSize;
public int PageNumber { get; set; } = Constants.DefaultPageNumber;
public string OrderBy { get; set; }
}
public class ProjectV20231
{
public int ID { get; set; }
public Guid GlobalID { get; set; }
public string Number { get; set; }
public string Name { get; set; }
public string Description { get; set; }
public string City { get; set; }
public bool Active { get; set; }
}
public enum OrderByDirection { Asc, Desc }
public class OrderByElement
{
public string Field { get; set; }
public OrderByDirection Direction { get; set; }
}
[Route("/projects", "GET")]
public class GetProjectsV20231 : IReturn<List<ProjectV20231>>
{
public string SearchTerm { get; set; }
public int Offset { get; set; }
public int Limit { get; set; }
public List<OrderByElement> OrderBy { get; set; }
public bool? Active { get; set; } = null;
}
public class ProjectsService : Service
{
public List<Project> Get(GetProjects request)
{
var result = new List<Project>
{
new Project() { Name = "2020.1" }
};
return result;
}
public List<ProjectV20231> Get(GetProjectsV20231 request)
{
var result = new List<ProjectV20231>
{
new ProjectV20231() { Name = "2023.1" }
};
return result;
}
}
We have a lot of existing services without any versioning. In this example that is GetProjects request and Project response. As long as there are no breaking changes we could keep the request and response DTOs without any version specification.
When we have a redesign of our API, we could introduce a new request and/or response DTO with the name extension V[ReleaseAndServicePackVersion], for example, GetProjectsV20231 and List ProjectV20231.
If partners or customers programmed against the 2020.1 version, then this should be set in the ServiceStack client or querystring:
client.Version = 20201;
client.Get(new GetProjects());
/api/projects?v=20201
If partners or customers want to use our new version, then they should update the version number and repair any breaking changes.
client.Version = 20231;
client.Get(new GetProjects());
Note: I still use GetProjects, although this probably won't work because they should use GetProjectsV20231 instead. But why should we specify the Version property of the client than any more?
If they don't use our DTOs, but are using the querystring approach, then the call should look transparent (although it is not, because the response is different).
/api/projects?v=20231
Questions:
Can we let ServiceStack show only the services which correspond to a specified version of the API? For example /api?v=20231 must only show the 2023.1 compatible services.
Is there a more convenient way to solve the versioning for our system? For ASP.NET a lot of research is already done, see https://github.com/dotnet/aspnet-api-versioning/wiki. Could this also be implemented in ServiceStack?
Should we also rename the GetProject request and Project response to GetProjectV20201 and ProjectV20201, otherwise ServiceStack don't know that these request and response are now version specific.
If 2023.2 version is out and there is no breaking change for GetProjects20231 then GetProjectsV20231 should be used, because it is the latest available version for the request. How can we configure/program ServiceStack to do that?
This Sounds like it's looking for a magic bullet to version typed APIs when there really isn't one, existing Typed clients are going to expect their Typed Request and Typed Response to remain the same which means the server needs to forever fulfill that API contract for as long as you want to make legacy versions of the Service available.
Versioning in Dynamic Languages
IMO dynamically routing requests to different based on a ?v=xx query parameter is only really feasible in dynamic languages who are better able to use model transformers to map how existing requests map to newer requests, call the newer API implementation then map their responses back to existing API contracts of existing Services, in ServiceStack it would look something like:
public class MyServices : Service
{
public object Any(GetProject request)
{
var v2Request = request.ConvertTo<GetProjectV2>();
var v2Response = Any(v2Request);
return v2Response.ConvertTo<GetProjectResponse>();
}
public object Any(GetProjectV2 request)
{
//...
return new GetProjectV2Response { ... }
}
}
This would take dramatically less effort to maintain in dynamic languages which can do the transformation with just mappers without introducing new types.
Versioning in Typed APIs
But adding new breaking API versions in typed APIs is going to result in an explosion of new API Request/Response, DTO and Data Model Types that's going to become less and less maintainable the more versions you need to support which is why the recommendation is to evolve your services by enhancing existing Services defensively so existing APIs can handle both old and new Requests.
API Version Info
Populating the Version in Request DTOs is to make it easier for APIs to determine which client version sent the request instead of trying to infer the version based on the heuristics of what parameters were sent with the API Request.
But if you want to make breaking changes with different Request/Response schemas you're going to need to create new Typed APIs. Given the effort to maintain multiple different API versions, making breaking changes should be a last resort. But if I wanted to enable it I'd put the version in the /path/info so it's given a permanent URL that wont change, e.g:
[Route("/v1/projects")]
public class GetProjects {}
[Route("/v2/projects")]
public class GetProjectsV2 {}
I'd disregard applying your external software versioning scheme to APIs (e.g. GetProjectV20231) and just version each API independently, primarily focusing on evolving them with backwards-compatible changes, and only adding new APIs when breaking changes are necessary.
Versioning Code Bases
New software releases could be updated to have the latest version of your APIs maintain the optimal name for the latest API e,g:
[Route("/v1/projects")]
public class GetProjectsV1 {}
[Route("/v2/projects")]
public class GetProjects {}
Newer versions of your software could rename the Server DTOs to their optimal names which should still support existing clients using existing DTOs since their schema contracts remain the same. They'll only need to update their clients when they want to use your software's latest typed API DTOs.
API Grouping
As for grouping your APIs I'd recommend using Tag Groups to group them, which can utilize your software versioning scheme to annotate APIs available in different versions, e.g:
[Tag("v2022.6")]
[Route("/v1/projects")]
public class GetProjectsV1 {}
[Tag("v2023.1")]
[Route("/v2/projects")]
public class GetProjects {}
[Tag("v2022.6"),Tag("v2023.1")]
[Route("/v1/projects/{Id}")]
public class GetProject {}
This will allow clients to browse APIs available in different versions in Metadata Pages as well as the built-in API Explorer.
It's also supported in Add ServiceStack Reference which can be used by clients to only generate DTOs for APIs in different versions.
Forgive me if I am just being thick but the Spyne documentation on headers seems a bit thin and the link to the sample code is broken. I think I found the sample code here but it only seems to access the headers in a listener callback function. I need access to it in the srpc method if possible.
What I would like to do is something like this (this does not work):
class MyRequest(ComplexModel):
Messages = Array(Unicode)
class MyHeader(ComplexModel):
TrackingID = ByteArray
class MySoapService(ServiceBase):
#srpc(MyRequest, _in_header=MyHeader)
def PostMessages(req, hdr):
logging.info(u'RECEIVED: {0:s}'.format(hdr.TrackingID))
If it helps, I am trying to replace a service written in .NET that just defines the message headers in the message contract like this:
[MessageContract]
public class MyRequest
{
[MessageHeader]
public Guid TrackingID { get; set; }
[MessageBodyMember]
public String[] Messages { get; set; }
}
You can't read header data from within an srpc function. #srpc is for existing functions that you don't want to touch. You should always use #rpc unless you know you need #srpc
Decorate your function using #rpc. This passes the rpc context (conventionally named ctx) as first argument to your function. Then, ctx.in_header is where you'll find the header data. You can also set ctx.out_header to alter outgoing response headers.
Also, pull requests for docs are pure gold to me :)
We are currently using ServiceStack for our web api which is 99% REST/JSON however we have one new message that we need to allow a SOAP endpoint for. (The client is an older BizTalk server and SOAP 12 is required.) We want to prevent SOAP on everything else but this one message. Is there a way to enable the SOAP Feature on a single message or service? What are the scopes to which SOAP can be specified?
In our AppHost Configure() we have removed the Features we want to disallow with EnableFeatures = Feature.All.Remove( Feature.Csv | Feature.Html | Feature.Jsv | Feature.Soap ) however this removes our ability to expose the SOAP12 WSDL. On the flip-side, not removing Feature.Soap enables SOAP for all POST messages which we need to prevent.
Any help is appreciated.
I have found the answer to my question.
ServiceStack has provided a way to specify what endpoint channels are available and to whom using the ServiceStack.ServiceHost.RestrictAttribute (https://github.com/ServiceStack/ServiceStack/wiki/Security). In order to limit the visibility of my message to only SOAP12:
//Request DTO
[DataContract(Namespace = Namespaces.Messages.NS_2013_01 )]
[Restrict(EndpointAttributes.Soap12 )]
public class Hello
{
public string Name { get; set; }
}
The visibility in my metadata is restricted appropriately:
Is there any solid guidance for generating hyperlinks for your resources in ASP.NET WebAPI? I've read a couple of posts on this:
http://codebetter.com/glennblock/2012/01/08/hypermedia-and-web-api-design-brain-dump-and-samples/
http://blog.ploeh.dk/2012/04/17/HyperlinkingWithTheASPNETWebAPI.aspx
Although informative, there appears to be no concrete guidance from Microsoft or otherwise in terms of how best to implement links for your resources (i.e. object model implemented using DTOs at the service layer). If we are moving towards using WebAPI to implement a true RESTful service, hyperlinking is crucial and I would have expected built in support / guidance for this in WebAPI.
A simple example I'm trying to implement this for is using a Contact entity which has a collection of Addresses and a collection of SupportIncident.
The class definitions based on the first article I've referenced would look something like so:
public class Link
{
public Uri Uri { get; set; }
public string Rel { get; set; }
public string Name { get; set; }
}
public class ContactDTO
{
public int ID { get; set; }
public string Name { get; set; }
public IList<AddressDTO> Addresses { get; set; }
public IList<IncidentDTO> Incidents{ get; set; }
public IList<Link> Links { get; set; }
}
WebAPI is great at exposing this model over HTTP (xml/json) and the GET/PUT/POST/DELETE action on the resource but in order to build a true RESTful service I would like to know if
a) Is there inherent support for link generation in WEBAPI?
b) Is there proper guidance for exposing the model above containing links to resources and how should the API handle PUT/POST if a client sends links as part of the payload. Should these be ignored?
In my opinion, Ben Foster did a great job on this. See the below blog post:
Generating Hypermedia links in ASP.NET Web API
The basic idea is that you will modify the ObjectContent's Value property on the way out through a message handler. This message handler delegates this work onto registered so-called "Response Enrichers" and each one of them has a chance to evaluate to see whether it can enrich the object type or not.
I built a sample application that demonstrates the use of Hypermedia in Web API here. There is another one here https://github.com/webapibook/issuetracker and Amy Palamountain has another good example here https://github.com/ammeep/hyper-library.
One of the main problems with using DTOs and links is that by default these DTOs will be serialized out as application/json or application/xml. Neither of those media types have any specifications for how links should be serialized. Therefore a client requires out-of-band knowledge on how to process those links.
To do hypermedia properly, you need to be using a hypermedia enabled media type, like xhtml, hal, collection+json, json-ld, siren.
I'm converting one of my existing service to become RESTful and I've got the basic things working with RestEasy. Some of my client apps should be able to execute both GET and POST requests to several services. I'm just seeking if there is any easy way around jax-rs to specify that API should accept both GETs and POSTs. Following you can find a test method, let me know if you see any way around without duplicating this in another class with #GET and #QueryParam.
#POST
#Path("/add")
public Response testREST(#FormParam("paraA") String paraA,
#FormParam("paraB") int paraB) {
return Response.status(200)
.entity("Test my input : " + paraA + ", age : " + paraB)
.build();
}
Just put your method body in another method and declare a public method for each HTTP verb:
#Controller
#Path("/foo-controller")
public class MyController {
#GET
#Path("/thing")
public Response getStuff() {
return doStuff();
}
#POST
#Path("/thing")
public Response postStuff() {
return doStuff();
}
private Response doStuff() {
// Do the stuff...
return Response.status(200)
.entity("Done")
.build();
}
}
As wikipedia says, an API is RESTful if it is a collection of resources with four defined aspects:
the base URI for the web service, such as http://example.com/resources/
the Internet media type of the data supported by the web service. This is often XML but can be any other valid Internet media type providing that it is a valid hypertext standard.
the set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or DELETE).
The API must be hypertext driven.
By diminishing the difference between GET and POST you're violating the third aspect.
If this scenario fits for all your resources you could create a ServletFilter which wraps the request and will return Get or Post everytime the method will be requested.